Autonomy Workflow Software

Owned by R D
Last updated: 2024-09-05 by Maxwell Lou
5 min read

Overview

These are instructions to get you working on a project.

Windows Subsystem for Linux (WSL) is not supported at this time. Please use regular Windows.

More detail in the Autonomy bootamp:

Setup

Project Repository

Once you are assigned a task for a project, follow the project links to the GitHub repository:

Git and GitHub

Git setup

Cloning the repository

Do this if you are starting on a project you have not been part of before.

Unlike in the Autonomy bootcamp, you do not fork the project repository. Instead, you are already added to the WARG GitHub organization as part of onboarding:

Go to GitHub and navigate to WARG’s copy of the repository as linked in the project repository Confluence page. Do not fork the repository!

Language setup

Autonomy uses Python and Dart (with Flutter).

If you have already setup the programming language, you do not need to do it again.

Python setup and virtual environment

Activate the environment:

Install required packages: See the project’s repository Confluence page for instructions.

Dart and Flutter

TODO

Development

Every time you want to change code on your computer.

If you haven’t already, pick an editor to use! Autonomy recommended IDEs:

Python setup

Activate the Python virtual environment

Install required packages: See the project’s repository Confluence page for instructions.

  • Usually your packages are already up to date, but there can be new packages required for the repositories.

Dart and Flutter setup

  1. Run flutter pub get to resolve dependencies

Starting a new task

  1. Make sure anything on the current branch has been saved, either through git commit or git stash.

  2. Checkout the main branch: git checkout main

  3. Update the code on your computer:

    1. git pull

    2. Run the project setup script: setup_project.ps1 for Windows or setup_project.sh for Linux/Mac

  4. Create a new branch based on main: git checkout -b new-branch-name

    1. Where new-branch-name is as described.

    2. Make sure to remember the branch name!

Continue a task

  1. Check which branch you are currently on: git status

  2. If you are not on the correct branch:

    1. Make sure anything on the current branch has been saved, either through git commit or git stash.

    2. Run: git checkout your-branch-name

      1. No -b , where your-branch-name is as described.

  3. Write and run the code!

    1. Ask questions if you need help.

    2. Follow the Autonomy style convention: and TODO Flutter Style Convention

  4. Run linters, formatters, and unit tests. While they don’t have to initially pass, they must pass before your code can be merged.

    1. Python:

      1. pylint .

      2. flake8 .

      3. black .

      4. pytest .

    2. Flutter:

      1. dart format .

      2. dart analyze

  5. Make a commit:

    1. Check which files you changed: git status

    2. Run: git add [files you changed] , where [files you changed] are the files you want to add to the commit.

      1. Use git add . if you want to add all of them (the dot means wildcard in Git).

    3. Run: git commit -m "Your commit message"

    4. When you’re ready to push your latest commits to GitHub: git push

      1. No harm in doing this after every commit.

Keeping up to date with main

The repository will keep changing as additional code is merged into main. You should update your own branch with the latest changes:

  1. Fetch: git fetch main

  2. Use 1 of the following methods:

    1. Merge: git merge main

      1. The difference between main and your current branch is squashed into 1 commit.

      2. Advantage: You only have to deal with conflicts once.

      3. Disadvantage: There may be a lot of conflicts to deal with at once.

    2. Rebase: git rebase main

      1. The base of your branch (wherever it split from main) is forwarded to the latest commit on main. Then, your commits are applied one at a time on the updated main.

      2. Advantage: Your commit history stays relatively stable.

      3. Disadvantage: There may be a conflict that you need to deal with for every commit in your branch (annoying if you have lots of commits).

  3. Go through your code to make sure nothing broke. Run the tests.

  4. Force push your changes to GitHub: git push -f

It’s recommended to do this between once per week to once per month.

Merge conflicts

Additional resources:

Since the repository is shared, someone else may have changed the same line of code as you have. As the main branch is the authoritative source, you only need to focus on conflicts with main.

Git will mark conflicts like this:

<<<<<<< HEAD your changed code ======= main's changed code >>>>>>> main

HEAD means the commit you are currently on.

To resolve the conflict, you have to choose and then implement 1 of the following:

  • Keep your code and discard main’s code.

  • Discard your code and keep main’s code.

  • Keep both.

  • Discard both.

  • Resolve it manually by typing something else.

Once all conflicts are resolved, add the files back to the commit: git add [file name]

Continue the rebase or merge:

  • Rebase: git rebase continue

  • Merge: git merge continue

If you think that you’ve messed up, you can abort: git [rebase or merge] abort

  • This will restore your branch to the condition immediately before the rebase or merge.

Example:

Your branch:

stuff if x > 5: # Changed from x > 4 more stuff

main:

stuff if x > 9: # Changed from x > 4 more stuff

What you see:

Conflict (rebasing your branch on main):

Final resolution (keep your code and discard main):

By deleting lines 2, 4-6 yourself or using an IDE to resolve.

Example:

Your branch:

main:

What you see:

Conflict (rebasing your branch on main):

Final resolution (keep both but also resolved manually):

By deleting lines 2, 6, 10 yourself and copying lines 7-9 above lines 3-5 or using an IDE to resolve (and then copying lines 7-9 above lines 3-5).

Pull request

Once your submission is ready for review, open a pull request (PR) from your branch to the WARG repository.

  1. Go to GitHub and navigate to WARG’s copy of the repository as linked in the project repository Confluence page.

  2. At the top, click Pull requests.

  3. To the right, click the green New pull request button.

  4. In the box, click the compare dropdown.

  5. Select your branch name.

    1. Do not open more than 1 pull request! The branch you select should contain (or eventually contain) all code which will be reviewed.

    2. Once you have an open PR, you can keep updating the same branch as you get feedback. You do not need to open another PR.

  6. Click on the green Create pull request button.

  7. Once you have an open PR and are ready for review, go to #auto-pr-reviews and create a new post with this message: My PR is ready for review: [link to your PR on GitHub]

    1. You may ping any relevant reviewers, including Autonomy Leads.

  8. The reviewers will review your PR (a message will be sent on Discord, and the comments will be on GitHub).

  9. Read the feedback and go back to continue your task. If any of the feedback is unclear or confusing, don’t hesitate to ask for clarification (make sure to send a message on Discord as well for visibility (e.g. I asked some questions as replies on GitHub ).

    1. Please do not resolve any of the comments that the reviewers may leave! It causes confusion for the reviewers since they use the resolved/unresolved state to confirm that the code meets the quality to their satisfaction. Instead, you can use a reaction or respond to the comment for your own tracking purposes.

    2. If you are ready for another review, repeat step 7 (you do not need to open a new PR).

For more information:

Completing the task

  1. Once your review is approved, navigate to your PR and click on the green squash and merge button.

    1. This automatically deletes your branch, as you do not need it anymore.

  2. In Asana, in the Task Progress column on the right, mark your task as done.

    1. Do not do this until you have merged your PR!

    2. Do not click the checkmark on the left!

  3. In #auto-pr-reviews react with a checkmark and remove the “open” tag on your post to mark it as complete.

  4. In the next Autonomy meeting, the project manager or lead clicks on the checkmark on the left.

You’ve completed the task!