Improve squashing documentation (#4668)

* Improve squashing documentation

Signed-off-by: Celeste Horgan <celeste@cncf.io>

* Apply suggestions from code review

Co-Authored-By: Bob Killen <killen.bob@gmail.com>

* Update contributors/guide/github-workflow.md

Co-Authored-By: Bob Killen <killen.bob@gmail.com>

Co-authored-by: Bob Killen <killen.bob@gmail.com>

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

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~<n>`, where `<n>` 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 <commit> = use commit
+  # r, reword <commit> = use commit, but edit the commit message
+  # e, edit <commit> = use commit, but stop for amending
+  # s, squash <commit> = use commit, but meld into previous commit
+  # f, fixup <commit> = 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.
+- [Create a Pull Request](#7-create-a-pull-request) using this branch.

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