Developer documentation

This document describes the best practices to be followed when working with Git and GitLab in this project.

The Goals

The goals we want to achieve are

• to have a codebase that is manageable and well documented
• to communicate among the members of the team as conveniently as possible
• to know and document what each one of us is doing

To achieve these goals, we will use the features of Git and Gitlab.

The recomended Workflow

Overview

1. Create an issue
2. Create a WIP merge request linking to the issue
3. Code, test, commit, code, test, commit, ... (in your branch)
4. Rebase your branch to master
5. Remove WIP from the merge request and invite someone to review your changes
6. Merge the code to master, remove the source branch and close the issue

Create an issue

Issues should be the primary source for documenting the development process. Label issues apropriatelly and use milestones to group issues.

Create a WIP merge request

WIP merge request is a way to create a merge request that can not be accidentally merged until is ready. Creating a WIP merge requests will help others on your team to better understand what it is that you are doing at the moment, and what is the purpose of different branches.

git fetch
git checkout 314-my-awesome-pi

Code, test, commit, code

Now you can finaly start coding.

Rebase your branch onto master

Rebasing is similar to merging, but the order of commits is rearanged so that we get a linear history. Make sure you read about Merging vs. Rebasing before you proceed.

To rebase your branch onto master

git fetch origin master
git checkout my-new-feature
git rebase master

After rebase, the commits of your branch will simply follow the tip of master branch.

If Git can not merge automatically, read the message carefully and proceed as suggested.

Invite someone to review your changes

Remove WIP from the merge request and invite someone to review your changes by mentioning them in a comment to the merge request.

Merge the code to master, remove the source branch and close the issue

Dos and don'ts

Everything should be in Git

Every contribution in text format and especially the code itself should be put into the Git version control system.

Don't commit in master!

Create a branch and merge with master when your changes are ready. The exceptions are minor chanages (code that does not affect core functionality like printing to console, etc.) or changes that do not touch the code itself, like documentation, comments, print statements, indentation, etc. The master branch should always pass all tests.

Commit frequently

If a change can be split into two separate changes that make sense on their own, then do this. Exceptions to the rule are the initial commits and commits of new features - however, the next rule still applies.

DOs and DON'Ts of commit messages

Don't:

• Don't end the summary line with a period as it is a title and these don't end with periods.

Do:

• Use the imperative mode when writing the summary line and describing what you have done, as if you were commanding someone - e.g., start the line with Fix, Add, Change instead of Fixed, Added, Changed;
• Leave the second line blank;
• Line break the commit message and make it readable without having to scroll horizontally (line = 80 characters).

See also

• GitHub's Writing good commit messages article
• chapter 5 of the Git book