Add guidelines for keeping a clean git history

dev-workflow.md

@@ -52,6 +52,7 @@ for further instructions. And beware of the following pitfalls:
     sure your PR title is concise and the description tells the reader enough
     to really understand what the PR is about. This is really important for
     reviewers!
+    - Read our [git history guidelines](git-history.md) for more details.
 
 1. **Request a review**. You can request reviews directly in *GitHub*. Also,
 don't be afraid to re-ask if no one has been on it after a couple of days.

git-history.md

@@ -0,0 +1,73 @@
+# Git History Guidelines
+
+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](https://github.com/in-toto/in-toto)), with a *main* branch,
+called `master` or `develop` (e.g.
+[in-toto/in-toto@develop](https://github.com/in-toto/in-toto/tree/develop)).
+Contributors work on their own *fork* of the *upstream* repository (e.g.
+[lukpueh/in-toto](https://github.com/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](https://github.com/lukpueh/in-toto/tree/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](https://github.com/theupdateframework/tuf/pull/804#issuecomment-440017361)
+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](commits.md) 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.
+
+#### Further reading
+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__
+- [Branching basics](https://git-scm.com/book/en/v1/Git-Branching)
+- [Rebasing basics](https://git-scm.com/book/en/v1/Git-Branching-Rebasing)
+- [`git rebase`](https://git-scm.com/docs/git-rebase)
+
+__Workflows__
+- [Feature branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)
+- [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)
+- [Syncing forks on GitHub](https://help.github.com/articles/syncing-a-fork/)
+
+__Bonus material__
+- [Interactive staging](https://git-scm.com/book/en/v1/Git-Tools-Interactive-Staging)
+- [Rewriting history](https://git-scm.com/book/en/v1/Git-Tools-Rewriting-History)