diff --git a/contributors/guide/contributor-cheatsheet/README.md b/contributors/guide/contributor-cheatsheet/README.md index 1e5f014e8..f1edc0d6c 100644 --- a/contributors/guide/contributor-cheatsheet/README.md +++ b/contributors/guide/contributor-cheatsheet/README.md @@ -356,6 +356,14 @@ phase of a PR revision. If you are unsure if you should squash your commits, it is better to err on the side of having more and leave it up to the judgement of the other contributors assigned to review and approve your PR. +Perform an interactive rebase to choose which commits you want to keep and which you want to squash, then force push your branch: + +``` +git rebase -i HEAD~3 +... +git push --force +``` + [contributor guide]: /contributors/guide/README.md diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md index 223767966..aae63e632 100644 --- a/contributors/guide/github-workflow.md +++ b/contributors/guide/github-workflow.md @@ -137,34 +137,101 @@ fork. Very small PRs are easy to review. Very large PRs are very difficult to review. -#### Squash and Merge +#### Squash commits -Upon merge (by either you or your reviewer), all commits left on the review -branch should represent meaningful milestones or units of work. Use commits to -add clarity to the development and review process. +After a review, prepare your PR for merging by squashing your commits. -Before merging a PR, squash any _fix review feedback_, _typo_, _merged_, and -_rebased_ sorts of commits. +All commits left on your branch after a review should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process. -It is not imperative that every commit in a PR compile and pass tests -independently, but it is worth striving for. +Before merging a PR, squash the following kinds of commits: -In particular, if you happened to have used `git merge` and have merge -commits, please squash those away: they do not meet the above test. +- Fixes/review feedback +- Typos +- Merges and rebases +- Work in progress -A nifty way to manage the commits in your PR is to do an [interactive -rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History), -which will let you tell git what to do with every commit: +Aim to have every commit in a PR compile and pass tests independently if you can, but it's not a requirement. In particular, `merge` commits must be removed, as they will not pass tests. -```sh -git fetch upstream -git rebase -i upstream/master -``` +To squash your commits, perform an [interactive +rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History): + +1. Check your git branch: + + ``` + git status + ``` + + Output is similar to: + + ``` + On branch your-contribution + Your branch is up to date with 'origin/your-contribution'. + ``` + +2. Start an interactive rebase using a specific commit hash, or count backwards from your last commit using `HEAD~`, where `` represents the number of commits to include in the rebase. + + ``` + git rebase -i HEAD~3 + ``` + + Output is similar to: + + ``` + pick 2ebe926 Original commit + pick 31f33e9 Address feedback + pick b0315fe Second unit of work + + # Rebase 7c34fc9..b0315ff onto 7c34fc9 (3 commands) + # + # Commands: + # p, pick = use commit + # r, reword = use commit, but edit the commit message + # e, edit = use commit, but stop for amending + # s, squash = use commit, but meld into previous commit + # f, fixup = like "squash", but discard this commit's log message + + ... + + ``` + +3. Use a command line text editor to change the word `pick` to `fixup` for the commits you want to squash, then save your changes and continue the rebase: + + ``` + pick 2ebe926 Original commit + squash 31f33e9 Address feedback + pick b0315fe Second unit of work + + ... + + ``` + + Output (after saving changes) is similar to: + + ``` + [detached HEAD 61fdded] Second unit of work + Date: Thu Mar 5 19:01:32 2020 +0100 + 2 files changed, 15 insertions(+), 1 deletion(-) + + ... + + Successfully rebased and updated refs/heads/master. + ``` +4. Force push your changes to your remote branch: + + ``` + git push --force + ``` For mass automated fixups (e.g. automated doc formatting), use one or more commits for the changes to tooling and a final commit to apply the fixup en masse. This makes reviews easier. +### Merging a commit + +Once you've received review and approval, your commits are squashed, your PR is ready for merging. + +Merging happens automatically after both a Reviewer and Approver have approved the PR. If you haven't squashed your commits, they may ask you to do so before approving a PR. + ### Reverting a commit In case you wish to revert a commit, use the following instructions. @@ -204,4 +271,4 @@ will create the PR branch inside the main repository rather than inside your for git push ${your_remote_name} myrevert ``` -- [Create a Pull Request](#7-create-a-pull-request) using this branch. \ No newline at end of file +- [Create a Pull Request](#7-create-a-pull-request) using this branch. diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md index a93d0a0a2..156c7e460 100644 --- a/contributors/guide/pull-requests.md +++ b/contributors/guide/pull-requests.md @@ -290,6 +290,8 @@ We might still ask you to clean up your commits at the very end for the sake of Each commit should have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended. +For more information, see [squash commits](./github-workflow.md#squash-commits). + **General squashing guidelines:** * Sausage => squash