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
  - 2.3.1 Python setup and virtual environment
  - 2.3.2 Dart and Flutter
3 Development
- 3.1 Python setup
  - 3.1.1 Activate the Python virtual environment
- 3.2 Dart and Flutter setup
- 3.3 Starting a new task
- 3.4 Continue a task
- 3.5 Keeping up to date with main
  - 3.5.1 Merge conflicts
- 3.6 Pull request
- 3.7 Completing the task

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:
1. git pull
2. Run the project setup script: setup_project.ps1 for Windows or setup_project.sh for Linux/Mac
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

Check which branch you are currently on: git status
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.
Write and run the code!
1. Ask questions if you need help.
2. 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.
1. Python:
  1. pylint .
  2. flake8 .
  3. black .
  4. pytest .
2. Flutter:
  1. dart format .
  2. dart analyze
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:

Fetch: git fetch main
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).
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.