Merge pull request #6347 from pymander/contributor-guide-style-guidelines

Update parts of the contributor guide to match the style guide

1 files changed, 70 insertions, 77 deletions

diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md
index 3c9f76fe..178c5854 100644
--- a/contributors/guide/github-workflow.md
+++ b/contributors/guide/github-workflow.md
@@ -2,43 +2,42 @@
 title: "GitHub Workflow"
 weight: 6
 description: |
-  An overview of the GitHub workflow used by the Kubernetes project. It includes
-  some tips and suggestions on things such as keeping your local environment in
-  sync with upstream and commit hygiene.
+  This document is an overview of the GitHub workflow used by the
+  Kubernetes project. It includes tips and suggestions on keeping your
+  local environment in sync with upstream and how to maintain good
+  commit hygiene.
 ---
 
 ![Git workflow](git_workflow.png)
 
-### 1 Fork in the cloud
+## 1. Fork in the cloud
 
 1. Visit https://github.com/kubernetes/kubernetes
 2. Click `Fork` button (top right) to establish a cloud-based fork.
 
-### 2 Clone fork to local storage
+## 2. Clone fork to local storage
 
 Per Go's [workspace instructions][go-workspace], place Kubernetes' code on your
 `GOPATH` using the following cloning procedure.
 
 [go-workspace]: https://golang.org/doc/code.html#Workspaces
 
-Define a local working directory:
+In your shell, define a local working directory as `working_dir`. If your `GOPATH` has multiple paths, pick
+just one and use it instead of `$GOPATH`. You must follow exactly this pattern,
+neither `$GOPATH/src/github.com/${your github profile name}/`
+nor any other pattern will work.
 
 ```sh
-# If your GOPATH has multiple paths, pick
-# just one and use it instead of $GOPATH here.
-# You must follow exactly this pattern,
-# neither `$GOPATH/src/github.com/${your github profile name/`
-# nor any other pattern will work.
 export working_dir="$(go env GOPATH)/src/k8s.io"
 ```
 
-> If you already do Go development on github, the `k8s.io` directory
-> will be a sibling to your existing `github.com` directory.
+If you already do Go development on github, the `k8s.io` directory
+will be a sibling to your existing `github.com` directory.
 
 Set `user` to match your github profile name:
 
 ```sh
-export user={your github profile name}
+export user=<your github profile name>
 ```
 
 Both `$working_dir` and `$user` are mentioned in the figure above.
@@ -62,71 +61,75 @@ git remote set-url --push upstream no_push
 git remote -v
 ```
 
-### 3 Branch
+## 3. Create a Working Branch
 
-Get your local master up to date:
+Get your local master up to date. Note that depending on which repository you are working from,
+the default branch may be called "main" instead of "master".
 
 ```sh
-# Depending on which repository you are working from,
-# the default branch may be called 'main' instead of 'master'.
-
 cd $working_dir/kubernetes
 git fetch upstream
 git checkout master
 git rebase upstream/master
 ```
 
-Branch from it:
+Create your new branch.
+
 ```sh
 git checkout -b myfeature
 ```
 
-Then edit code on the `myfeature` branch.
+You may now edit files on the `myfeature` branch.
 
-#### Build
+### Building Kubernetes
 
-This workflow is process-specific; for quick start build instructions for [kubernetes/kubernetes](https://git.k8s.io/kubernetes) please [see here](/contributors/devel/development.md#building-kubernetes-on-a-local-osshell-environment).
+This workflow is process-specific. For quick-start build instructions for [kubernetes/kubernetes](https://git.k8s.io/kubernetes), please [see here](/contributors/devel/development.md#building-kubernetes-on-a-local-osshell-environment).
 
-### 4 Keep your branch in sync
+## 4. Keep your branch in sync
 
-```sh
-# Depending on which repository you are working from,
-# the default branch may be called 'main' instead of 'master'.
+You will need to periodically fetch changes from the `upstream`
+repository to keep your working branch in sync. Note that depending on which repository you are working from,
+the default branch may be called 'main' instead of 'master'.
 
-# While on your myfeature branch
+Make sure your local repository is on your working branch and run the
+following commands to keep it in sync:
+
+```sh
 git fetch upstream
 git rebase upstream/master
 ```
 
-Please don't use `git pull` instead of the above `fetch` / `rebase`. `git pull`
-does a merge, which leaves merge commits. These make the commit history messy
+Please don't use `git pull` instead of the above `fetch` and
+`rebase`. Since `git pull` executes a merge, it creates merge commits. These make the commit history messy
 and violate the principle that commits ought to be individually understandable
-and useful (see below). You can also consider changing your `.git/config` file via
+and useful (see below). 
+
+You might also consider changing your `.git/config` file via
 `git config branch.autoSetupRebase always` to change the behavior of `git pull`, or another non-merge option such as `git pull --rebase`.
 
-### 5 Commit
+## 5. Commit Your Changes
 
-Commit your changes.
+You will probably want to regularly commit your changes. It is likely that you will go back and edit,
+build, and test multiple times. After a few cycles of this, you might
+[amend your previous commit](https://www.w3schools.com/git/git_amend.asp).
 
 ```sh
 git commit
 ```
-Likely you go back and edit/build/test some more then `commit --amend`
-in a few cycles.
 
-### 6 Push
+## 6. Push to GitHub
 
-When ready to review (or just to establish an offsite backup of your work),
-push your branch to your fork on `github.com`:
+When your changes are ready for review, push your working branch to
+your fork on GitHub.
 
 ```sh
-git push -f ${your_remote_name} myfeature
+git push -f <your_remote_name> myfeature
 ```
 
-### 7 Create a pull request
+## 7. Create a Pull Request
 
-1. Visit your fork at `https://github.com/$user/kubernetes`
-2. Click the `Compare & Pull Request` button next to your `myfeature` branch.
+1. Visit your fork at `https://github.com/<user>/kubernetes`
+2. Click the **Compare & Pull Request** button next to your `myfeature` branch.
 3. Check out the pull request [process](/contributors/guide/pull-requests.md) for more details and
    advice.
 
@@ -134,7 +137,7 @@ _If you have upstream write access_, please refrain from using the GitHub UI for
 creating PRs, because GitHub will create the PR branch inside the main
 repository rather than inside your fork.
 
-#### Get a code review
+### Get a code review
 
 Once your pull request has been opened it will be assigned to one or more
 reviewers.  Those reviewers will do a thorough code review, looking for
@@ -146,7 +149,7 @@ fork.
 
 Very small PRs are easy to review.  Very large PRs are very difficult to review.
 
-#### Squash commits
+### Squash commits
 
 After a review, prepare your PR for merging by squashing your commits.
 
@@ -161,8 +164,7 @@ Before merging a PR, squash the following kinds of commits:
 
 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.
 
-To squash your commits, perform an [interactive
-rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
+To squash your commits, perform an [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
 
 1. Check your git branch:
 
@@ -170,7 +172,7 @@ rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
   git status
   ```
 
-  Output is similar to:
+  The output should be similar to this:
 
   ```
   On branch your-contribution
@@ -183,7 +185,7 @@ rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
   git rebase -i HEAD~3
   ```
 
-  Output is similar to:
+  The output should be similar to this:
 
   ```
   pick 2ebe926 Original commit
@@ -214,7 +216,7 @@ rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
 
   ```
 
-  Output (after saving changes) is similar to:
+  The output after saving changes should look similar to this:
 
   ```
   [detached HEAD 61fdded] Second unit of work
@@ -231,17 +233,17 @@ rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History):
   git push --force
   ```
 
-For mass automated fixups (e.g. automated doc formatting), use one or more
+For mass automated fixups such as 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
+## 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.
+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
+## Reverting a commit
 
 In case you wish to revert a commit, use the following instructions.
 
@@ -249,12 +251,8 @@ _If you have upstream write access_, please refrain from using the
 `Revert` button in the GitHub UI for creating the PR, because GitHub
 will create the PR branch inside the main repository rather than inside your fork.
 
-- Create a branch and sync it with upstream.
-
+- Create a branch and sync it with upstream. Note that depending on which repository you are working from, the default branch may be called 'main' instead of 'master'.
   ```sh
-  # Depending on which repository you are working from,
-  # the default branch may be called 'main' instead of 'master'.
-  
   # create a branch
   git checkout -b myrevert
 
@@ -262,25 +260,20 @@ will create the PR branch inside the main repository rather than inside your for
   git fetch upstream
   git rebase upstream/master
   ```
-- If the commit you wish to revert is a:<br>
-  - **merge commit:**
-
-    ```sh
-    # SHA is the hash of the merge commit you wish to revert
-    git revert -m 1 SHA
-    ```
-
-  - **single commit:**
-
-    ```sh
-    # SHA is the hash of the single commit you wish to revert
-    git revert SHA
-    ```
+- If the commit you wish to revert is a *merge commit*, use this command:
+  ```sh
+  # SHA is the hash of the merge commit you wish to revert
+  git revert -m 1 <SHA>
+  ```
+  If it is a *single commit*, use this command:
+  ```sh
+  # SHA is the hash of the single commit you wish to revert
+  git revert <SHA>
+  ```
 
 - This will create a new commit reverting the changes. Push this new commit to your remote.
+  ```sh
+  git push <your_remote_name> myrevert
+  ```
 
-```sh
-git push ${your_remote_name} myrevert
-```
-
-- [Create a Pull Request](#7-create-a-pull-request) using this branch.
+- Finally, [create a Pull Request](#7-create-a-pull-request) using this branch.