Git Workflow and Conventions

General Git Workflow

• If you haven't already, clone the repository with git clone --recursive https://github.com/space-concordia-robotics/robotics-prototype.git to whichever folder you want to hold your Git repositories
• It's a good habit to always git pull when opening the project to ensure you have the most up-to-date state of the project.
• If it doesn't already exist, create a new branch based off the issue that you're working on. If the issue doesn't exist, feel free to open one (and/or contact the Software lead).
• Make changes to the code. Good practice is to make a small incremental and logically grouped changes, upload it, then repeat
• Stage the modified files that you wish to upload
  • Use git status to see which files are staged for a commit already (will be green), and which are not yet (will be red).
  • Use git add <filename> to add files to staging area (other options for git add exist as well - you can see these options with git add --help)
• Commit your changes
  • git commit -m "[#13][#20] Update feature X to include Y and remove Z" (see Commit Messages for more details about this step)
• Push your commit(s) to the remote repository
  • git pull - always pull before you push (resolve merge conflicts if there are any)
  • git push - push your commit(s)

Feature Branches

Branch Creation

When working on a feature, first create your new branch off of master:

• To make sure you're on the master branch, type git branch you should see a * symbol in front of master.
• If you're not on master you can switch to it with git checkout master.
• Create your branch with git branch <newbranchname> (see Branch Names for naming conventions)
• Switch to your new branch with git checkout <newbranchname>
• Declare your branch to the world with git push -u origin <newbranchname>. Now you can use the workflow defined above to work on your issue! When you're done with your task you can open a Pull Request to get the review process started.

Remember to always git pull before you git push!

Slack GitHub Commit Spam Channel

In Slack we are using a GitHub integration tool for the channel #robotics-git, where we can see the commits of members when they are pushed. Be aware though that whenever a new branch is created, the list of branches that are being tracked needs to be manually updated if you want those commit messages to appear.

If a new branch has been created and you have the proper administrative rights:

1. Click on the Slack team's name in the top left corner > Customize Slack >Configure apps > Github Notifications > Edit configuration icon for robotics-prototype

2. Under Repositories with robotics-prototype selected, in the input field on the right side append the name of the newly created branch to the list. Note how the delimiter is , (a comma followed by a space)

NOTE: You will need the appropriate permissions to do this. Most likely you will need to ask Peter to add it for you.

Naming Conventions

Branch Names

Every feature branch should have a corresponding issue. If there isn't one already, create one for your branch.

Every issue is automatically assigned an id number (present at the end of the URL).

Branch names should be all lower case, dash separated and end with the corresponding issue's ID number.

Example:

enable-disable-wheel-controls-34

fix-broken-links-35

As for the name itself, you can either use the issue title or a shortened alternative.

Commit Messages

Try to keep commit messages relatively short and concise, describing the changes you are introducing with it to the state of the project. Add the issue number(s) related to your commit (if applicable) at the start of the commit.

You should separate your commit into two sections, the title (brief summary of the changes) and the description (optional extra clarification). Begin the title with a capital letter and try to keep it not more than 50 characters long. Make sure to always keep the title in present tense (this saves 1-2 chars).

Example (assuming that this commit is related both to issue #13 and #20):

git commit -m "[#13] Update feature X to include Y and remove Z"

If you haven't already, it is strongly recommended to setup our git hooks to help automate our convention practices for you.

To make a commit with both a title and a longer description you have a few options:

• Type git commit and press enter, which will open your default text editor (nano, vim, etc)

• Type git commit -m " and type in the title, then without entering the closing quotation mark press enter twice. Now you're on the second next line and can begin typing a detailed description. You can keep moving to new lines until you close the string with ". Note that while the title must be in present tense, the description may be in any tense and generally any form you like.

git commit -m "[#33] Add commands for rover listener
> 
> List of commands added:
> z --> stop all motors
> o --> reset angle values
> q --> terminate the script
> a --> get debug messages
> p --> ping rover MCU
> "

• This thread has some other options/explanations.

You may also use git commit --amend to open up the most recent commit message in the default text editor. Ideally you want to use this functionality before pushing said commit.

Pull Requests (PRs)

Assignee

When a reviewer creates a publishes review and adds comments, as the Assignee you are expect to follow up on every comment raised by making changes to the code, replying to the comments when done or otherwise. It's up to the reviewer to resolve threads they have started.

Ideally the developer opening the PR should provide steps how to test the feature/fix. Unit tests are also appreciated (but currently not as strictly necessary as the testing steps). All this makes it more easy to review and enforces good documentation practices.

Reviewer

One of the main points of using git is to work on software in teams and effectively collaborate with each other. In our case it means when people work on their branches, after they think they are done with the coding for the feature they open a PR so that it can be reviewed by other members before merging the new code into the develop branch.

Static review of the code (just reading it, not running it) can be very helpful in terms of maintaining the quality of new code being merged into master. At the very least the person reviewing the PR should actually read all the changes. If possible, the reviewer should actually run and test the code and state how they managed to do that in their review summary comment.

Description Formatting

The PR template provided will guide you on how to fill format you PR description.