All of our projects follow a fork + feature branch workflow. That is, every
project has a main upstream repository (e.g.
in-toto/in-toto), with a main branch,
called master or develop (e.g.
in-toto/in-toto@develop).
Contributors work on their own fork of the upstream repository (e.g.
lukpueh/in-toto). For every feature or
fix they are working on, they create a feature branch, with a descriptive
name (e.g.
lukpueh/in-toto@threshold-comment-fix).
A feature branch of a fork is incorporated into the main branch of the
upstream repository by submitting a pull request.
The rest of this document presents some guidelines to keep our projects' git histories clean.
TL;DR
Avoid merge commits in your feature branch. You can use git rebase to sync
your feature branch with the main branch in upstream and also to keep
your git history clean.
Choose the right base for your feature branch In most cases you will base your feature branch on the main branch of your fork. Make sure that the main branch of your fork is in sync with the main branch of upstream so that you don't work on outdated code. Updating the main branch of your fork should not require merge commits, unless you have commited directly to your main branch, which you shouldn't!
Keep the base of your feature branch in sync with upstream
While you are working on your feature branch the main branch might move
forward, because some other work was merged into the main branch. Check
regularly, especially before you submit a pull request, if the
base of your feature branch has moved forward. If it has, use git rebase
to update the base and fix conflicts as they occur. (git fetch --all and
git rebase <upstream>/<main branch> instead of git pull).
Here's
an example in practice.
Tricks to keep the history of your feature branch clean (bonus task)
A clean history also means that you split your work into sensible chunks, i.e.
commits (see our commit guidelines for more details). You don't
even need to worry about this while coding. You can use git add in
interactive or patch mode to create multiple logically separated
commits from a huge diff. Or use git rebase in interactive mode to rewrite
the history of your feature branch to your hearts content.
Rebasing in an open pull request Once you have submitted a pull request and you are receiving review comments, please avoid rebasing, as it makes it harder for reviewers to follow any changes that they requested. However, if GitHub notifies you about conflicts, you should rebase as described above, while fixing those conflicts. Ideally, you do that after addressing all review comments and having received another round of review.
Consider reading the resources listed below, especially if some of above is unclear, you can also always reach out to someone on the lab.
Git branching and rebasing
Workflows
Bonus material