From 3c25ac2e572fb7596edbf60c543e17e845d19903 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Tue, 13 Nov 2018 19:15:14 +0100 Subject: [PATCH 1/5] Add git history guidlines Give high-level instructions about fork + feature branch workflow and tips and tricks to keep the git history clean (using rebase). --- git-history.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 git-history.md diff --git a/git-history.md b/git-history.md new file mode 100644 index 0000000..b326466 --- /dev/null +++ b/git-history.md @@ -0,0 +1,69 @@ +# 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 +regularily, 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. + +__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. + +__Resolve conflicts in an open *pull request*__ Once you have submitted a *pull +request* and you are receiving reviews and comments, you should avoid rebasing, +as it makes it harder to follow your changes on GitHub. However, if GitHub +notifies you about conflicts, you should rebase and fix the conflicts. Ideally, +you would do that after you addressed all review comments. + +#### 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) \ No newline at end of file From a762b244c201c6d937fbbe605096cec6449e9ebc Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 14 Nov 2018 12:52:05 +0100 Subject: [PATCH 2/5] Link to git history guidlines in dev workflow --- dev-workflow.md | 1 + 1 file changed, 1 insertion(+) 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. From d3e646348910d7e7f22c2e533d0b8b34eacb4046 Mon Sep 17 00:00:00 2001 From: Sebastien Awwad Date: Wed, 21 Nov 2018 11:28:25 +0100 Subject: [PATCH 3/5] Add fetch and rebase command example Add example that shows how to fix conflicts using git rebase. NOTE: Amending this commit to test how GitHub fares with rebases. --- git-history.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/git-history.md b/git-history.md index b326466..dbe3769 100644 --- a/git-history.md +++ b/git-history.md @@ -34,7 +34,10 @@ 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 regularily, 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. +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. @@ -66,4 +69,4 @@ __Workflows__ __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) \ No newline at end of file +- [Rewriting history](https://git-scm.com/book/en/v1/Git-Tools-Rewriting-History) From c3506216b012439997a971760cbb46ccb0e8840d Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Fri, 30 Nov 2018 10:39:27 +0100 Subject: [PATCH 4/5] Fix typo --- git-history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git-history.md b/git-history.md index dbe3769..fa4d3ce 100644 --- a/git-history.md +++ b/git-history.md @@ -32,7 +32,7 @@ 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 -regularily, especially before you submit a *pull request*, if the +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`). From f26e6fda8aedccc7f912f97806cecdf73aab4ff5 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Fri, 30 Nov 2018 10:39:34 +0100 Subject: [PATCH 5/5] Slightly reword rebasing on open PR paragraph Emphasize on avoiding rebasing on open PRs, to make reviews easier, but allowing rebasing to fix conflicts. --- git-history.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/git-history.md b/git-history.md index fa4d3ce..6c20036 100644 --- a/git-history.md +++ b/git-history.md @@ -47,11 +47,12 @@ even need to worry about this while coding. You can use `git add` in commits from a huge diff. Or use `git rebase` in `interactive` mode to rewrite the history of your *feature* branch to your hearts content. -__Resolve conflicts in an open *pull request*__ Once you have submitted a *pull -request* and you are receiving reviews and comments, you should avoid rebasing, -as it makes it harder to follow your changes on GitHub. However, if GitHub -notifies you about conflicts, you should rebase and fix the conflicts. Ideally, -you would do that after you addressed all review comments. +__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