Like many F/OSS developers, I’m a heavy user of GitHub, collaborating on many projects which use the typical “fork & pull” workflow based on pull requests. The GitHub documentation on pull requests covers this workflow fairly comprehensively, but there seems to be one area which is significantly lacking in detail: why and how to amend existing pull requests. The article simply says:
After your pull request is sent, any new commits pushed to your branch will automatically be added to the pull request. This is especially useful if you need to make more changes.
The problem is that this completely ignores the fact that there are often very good reasons for amending existing commits within the pull request, not just for adding new commits it.
Why amend an existing pull request?
A peer review cycle can potentially reveal many issues which make the pull request unready for merging, e.g.
- bugs in the proposed code changes
- missing features in the proposed code changes
- incomplete test coverage
- incomplete documentation changes
- style inconsistencies (including whitespace issues)
- incorrect or incomplete commit messages
- the commits violate the rule of one logical change per commit
- some changes are outside the scope of the pull request
This is of course what makes peer review of pull requests so valuable: the problems can be addressed even before they hit the
master branch, which helps maintain high quality in the development trunk. But then how do we address the issues?