diff --git a/dev-workflow.md b/dev-workflow.md index f9b31fa..fdc22ec 100644 --- a/dev-workflow.md +++ b/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. diff --git a/git-history.md b/git-history.md new file mode 100644 index 0000000..6c20036 --- /dev/null +++ b/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 /
` 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)