Please squash all commits before merging pull requests

GitHub pull requests are a great tool, but they can also complicate the
commit log. What once was a relatively linear commit history can become a
mess of parallel "branches" over long periods of time. This is most obvious
in tools like gitk, but the GitHub history is also confusing because the
commits from a single pull request may be scattered throughout the commit
log.

This is most important for merges from upstream into the pull request as
the author keeps the branch up-to-date. These merges appear as commits in
the history once the pull request is merged. However, updates based on
review feedback or fixing spelling also appear as separate commits, which
can make it hard to see exactly what was committed.

See http://programmers.stackexchange.com/a/263172 for additional
explanation.


I propose:

To minimize the impact, please squash all commits in a pull request into a
single commit before merging it. Committers (editors) should make sure
commits have been squashed before merging their own or others' pull
requests.

There will be exceptions. For example, sometimes a pull request might have
multiple distinct actions (i.e. do something then rename a variable), in
which case the branch might be squashed into two commits.


Details:
The squashing happens in the branch and updates the pull request before it
is merged. Thus, you should be able to view the results in GitHub before
merging into the mainline. Most of the magic happens with "git rebase -i
<base-commit>" on your local repository. Be sure to pick the right
base-commit for <base-commit>. (For merges, this appears to be the master
branch.) Then, you need to (force) push your changes to GitHub.

The one drawback is that the previous commits are wiped from the commit
history for your branch. That means the review history and comments are no
longer browsable (as far as I can tell). They appear to still be available
if you have the URLs, though. Thus, if you want to maintain history, it
might make sense to create a new branch and/or pull request with the
squashed commit.

Note: You can also fix commit messages using the "reword" feature of "git
rebase -i". For example, if you forgot to refer to the issue number.

References:

   - http://programmers.stackexchange.com/a/263172
   -
   https://github.com/ginatrapani/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit
   - https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
   -
   http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit

Received on Friday, 4 September 2015 18:14:15 UTC