[WIP] Add guidance for reviewers about squashing commits

kubernetes · Aug 28, 2022 · 47cd2f9 · 47cd2f9
1 parent 7ddd6e6
commit 47cd2f9
Showing 1 changed file with 16 additions and 0 deletions.
diff --git a/content/en/docs/contribute/review/for-approvers.md b/content/en/docs/contribute/review/for-approvers.md
@@ -222,4 +222,20 @@ https://github.com/kubernetes/kubernetes/issues.
 If this is a documentation issue, please re-open this issue.
 ```
 
+### Squashing
 
+As an approver reviewing various pull requests (PRs), there are different cases where you might help a contributor squash their commits, do it for them, or advise against squashing altogether:
+
+**Contributor squashes**: New contributors might not be aware of the [that they should squash commits in their pull requests (PRs)](/docs/contribute/new-content/open-a-pr#squashing-commits). You can provide this link and arrange or offer help if they need it. There is also a [GitHub Workflow](https://www.k8s.dev/docs/guide/github-workflow/) topic with diagrams on the Kubernetes Developers site.
+
+**You squash**: If a contributor might have difficulty squashing commits, or there is urgency to merge the PR, you can perform the squash for them:
+- The kubernetes/website repo is [configured to allow commit squashing for pull request merges](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). (TBD is it?) Simply select the squash commits button
+- In the PR, if the contributor enables maintainers to manage the PR, you can squash their commits and update their fork with the result. Before you squash, advise them to save and push their latest changes to the PR. After you squash, advise them to pull the squashed commit to their local clone.
+- You can get GitHub to squash the commits by using a label, so that Tide / GitHub performs the squash, or by clicking the TBD button when you merge the PR.
+
+**Avoid squashing**
+- If one of the commits does something broken or unwise, and the last commit reverts this error, don't squash the commmits. Even though the "Files changed" tab in the PR on GitHub and the Netlify preview both look OK, this merging this PR might create rebase or merge conflicts for other folks.
+Intervene as you see fit to avoid that risk to other contributors.
+
+**Never squash**
+- If you're launching a localization or releasing the docs for a new version, you are merging in a branch that's not from a user's fork, _never squash the commits_. Not squashing is essential because you must maintain the commit history for those files.