Autonomy Workflow Software
- 1 Overview
- 2 Setup
- 2.1 Project Repository
- 2.2 Git and GitHub
- 2.2.1 Git setup
- 2.2.2 Cloning the repository
- 2.3 Language setup
- 3 Development
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: Autonomy Bootcamp
Setup
Project Repository
Once you are assigned a task for a project, follow the project links to the GitHub repository: 2023-2024 Project List
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: New Member 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
WIP - Flutter Setup
IMACS Setup
Development
Every time you want to change code on your computer.
If you haven’t already, pick an editor to use! Autonomy recommended IDEs: Integrated Development Environments (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
Run
flutter pub get
to resolve dependencies
Starting a new task
Make sure anything on the current branch has been saved, either through git commit or git stash.
Checkout the main branch:
git checkout main
Update the code on your computer:
git pull
Run the project setup script:
setup_project.ps1
for Windows orsetup_project.sh
for Linux/Mac
Create a new branch based on main:
git checkout -b new-branch-name
Where
new-branch-name
is as described.Make sure to remember the branch name!
Continue a task
Check which branch you are currently on:
git status
If you are not on the correct branch:
Make sure anything on the current branch has been saved, either through git commit or git stash.
Run:
git checkout your-branch-name
No
-b
, whereyour-branch-name
is as described.
Write and run the code!
Ask questions if you need help.
Follow the Autonomy style convention: Python Style Convention and TODO Flutter Style Convention
Run linters, formatters, and unit tests. While they don’t have to initially pass, they must pass before your code can be merged.
Python:
pylint .
flake8 .
black .
pytest .
Flutter:
dart format .
dart analyze
Make a commit:
Check which files you changed:
git status
Run:
git add [files you changed]
, where[files you changed]
are the files you want to add to the commit.Use
git add .
if you want to add all of them (the dot means wildcard in Git).
Run:
git commit -m "Your commit message"
When you’re ready to push your latest commits to GitHub:
git push
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:
Fetch:
git fetch main
Use 1 of the following methods:
Merge:
git merge main
The difference between main and your current branch is squashed into 1 commit.
Advantage: You only have to deal with conflicts once.
Disadvantage: There may be a lot of conflicts to deal with at once.
Rebase:
git rebase main
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.
Advantage: Your commit history stays relatively stable.
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).
Go through your code to make sure nothing broke. Run the tests.
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.
Go to GitHub and navigate to WARG’s copy of the repository as linked in the project repository Confluence page.
At the top, click Pull requests.
To the right, click the green New pull request button.
In the box, click the compare dropdown.
Select your branch name.
Do not open more than 1 pull request! The branch you select should contain (or eventually contain) all code which will be reviewed.
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.
Click on the green Create pull request button.
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]
You may ping any relevant reviewers, including Autonomy Leads.
The reviewers will review your PR (a message will be sent on Discord, and the comments will be on GitHub).
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
).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.
If you are ready for another review, repeat step 7 (you do not need to open a new PR).
For more information: Reviewing Code
Completing the task
Once your review is approved, navigate to your PR and click on the green squash and merge button.
This automatically deletes your branch, as you do not need it anymore.
In Asana, in the Task Progress column on the right, mark your task as done.
Do not do this until you have merged your PR!
Do not click the checkmark on the left!
In #auto-pr-reviews react with a checkmark and remove the “open” tag on your post to mark it as complete.
In the next Autonomy meeting, the project manager or lead clicks on the checkmark on the left.
You’ve completed the task!