I would like to have a discussion about potentially establishing some guidelines for commits submitted via pull requests. I will start by describing my workflow and a common pattern that concerns me, I will then make some recommendations that I believe will produces an easier to follow commit history. I chose the word guidelines because I believe they need to be just that. If they where hard rules, I think they would interfere with 'getting things done'.
I believe that the commit history should be less about the specific order in which the changes where made, and more about being a series of logical evolutionary steps that the code has gone though. Counter to that ideal, I find that my development processes is somewhat chaotic, in as much as I start on a piece of code, then move on to the next, then often have to go back and fix or extend an existing piece of code before proceeding. In an effort to bring order to the chaos, I try to take the approach of making lots of little independent commits, then reordering and combining those commits into a coherent series commits that make the evolution easily apparent.
Merging master into a feature branch can make it difficult to see changes made to resolve conflicts as you have to pick out the fixes from the merge. This is particularly problematic for non-trivial conflicts. It also has the potential to change the identity of master if the request is subsequently pulled instead of merged into master. In this case, master appears to be a feature branch will all kinds of other pulls/merges and the original feature branch looks like master. In the following image, the highlighted commits show points where master was merged into a feature branch that was then pulled into master making it difficult to follow the main line of development as it jumps around. In this image, master starts, at the bottom, as the green line, then is merged into the red line before finally being merged into the black line.
- history-problem-1.jpg (7.34 KiB) Viewed 3664 times
- Avoid merging master into feature branches, if changes from master are required, re-base the feature branch onto master.
- Whenever possible, pull requests should be re-based against master prior to being submitted.
- If continuing development on a feature branch that has been merged into master, pull the merge commit into the feature branch so the the feature branch now diverges from master at that point instead of when the feature branch was originally created.
- If shared development is required off master, then create a separate branch to represent that shared development, and treat it as a master branch.
