Damien Regad
2014-03-29 14:04:54 UTC
Hi all,
As much as I love pasta, I'd rather avoid having our Git history look
like a plate of spaghetti, and keep it as linear as possible instead ;-)
Grangeway's recent series of merge commits is a typical example of what
I strongly believe we should try to avoid. Just have a look at the
attached screenshot, and I'm sure you'll agree...
When merging pull requests, especially for older branches, please follow
these guidelines:
1. Rebase your branch on top of the latest git HEAD
git fetch origin
git rebase master FeatureBranch
Resolve conflicts when you rebase, and don't forget to re-test the code
if there were any.
2a. Merge the branch manually
git checkout master
git merge --no-ff FeatureBranch
The --no-ff flag forces the creation of a merge commit, so that the
individual commits in the branch stand out as a unit. This makes future
maintenance and searches through history easier.
Notes:
- this is exactly what Github does when you click the "Merge Pull
Request" button.
- if the branch has a single commit, then the --no-ff flag is not
necessary and should not be used (consequently, we should merge manually
instead of using the Github button for such pull requests).
Attention: make sure to provide a descriptive merge commit message
In other words, do *not* keep the Git default text like "Merge branch
'variable-naming' of https://github.com/grangeway/mantisbt into
grangeway-variable-naming".
These messages are essentially useless, as they do not provide any
useful information regarding what the merged branch was about. Instead,
briefly describe what the purpose of the branch was, and reference the
Github pull request and/or Mantis issue(s) Id.
Note: if I'm not mistaken, when you merge from Github, this text is
taken from the pull request's subject and description (1st comment).
2b. Merge the pull request from Github
As an alternative to 2a, after rebasing (step 1) you can simply force
push the rebased branch to your Github fork.
git push -f YourFork FeatureBranch
The pull request will be automatically updated, and then you can simply
click the "Merge pull request" button in Github.
For reference, here are a couple of examples of what I consider "good"
merge commits:
- Manual merge with custom commit message
https://github.com/mantisbt/mantisbt/commit/b5194d98fd
- Merge from Github
https://github.com/mantisbt/mantisbt/commit/e3ed007f3d
Of course in the case of a complex branch, especially one where merges
*from* master have taken place, it may be too difficult / not worth the
effort to rebase, in which case a "normal" merge is acceptable. However
we should try to keep these at a minimum to avoid cluttering the history.
Thanks for your understanding and consideration.
Damien
PS: I'll add this to the wiki and/or the developer's guide later as time
allows.
As much as I love pasta, I'd rather avoid having our Git history look
like a plate of spaghetti, and keep it as linear as possible instead ;-)
Grangeway's recent series of merge commits is a typical example of what
I strongly believe we should try to avoid. Just have a look at the
attached screenshot, and I'm sure you'll agree...
When merging pull requests, especially for older branches, please follow
these guidelines:
1. Rebase your branch on top of the latest git HEAD
git fetch origin
git rebase master FeatureBranch
Resolve conflicts when you rebase, and don't forget to re-test the code
if there were any.
2a. Merge the branch manually
git checkout master
git merge --no-ff FeatureBranch
The --no-ff flag forces the creation of a merge commit, so that the
individual commits in the branch stand out as a unit. This makes future
maintenance and searches through history easier.
Notes:
- this is exactly what Github does when you click the "Merge Pull
Request" button.
- if the branch has a single commit, then the --no-ff flag is not
necessary and should not be used (consequently, we should merge manually
instead of using the Github button for such pull requests).
Attention: make sure to provide a descriptive merge commit message
In other words, do *not* keep the Git default text like "Merge branch
'variable-naming' of https://github.com/grangeway/mantisbt into
grangeway-variable-naming".
These messages are essentially useless, as they do not provide any
useful information regarding what the merged branch was about. Instead,
briefly describe what the purpose of the branch was, and reference the
Github pull request and/or Mantis issue(s) Id.
Note: if I'm not mistaken, when you merge from Github, this text is
taken from the pull request's subject and description (1st comment).
2b. Merge the pull request from Github
As an alternative to 2a, after rebasing (step 1) you can simply force
push the rebased branch to your Github fork.
git push -f YourFork FeatureBranch
The pull request will be automatically updated, and then you can simply
click the "Merge pull request" button in Github.
For reference, here are a couple of examples of what I consider "good"
merge commits:
- Manual merge with custom commit message
https://github.com/mantisbt/mantisbt/commit/b5194d98fd
- Merge from Github
https://github.com/mantisbt/mantisbt/commit/e3ed007f3d
Of course in the case of a complex branch, especially one where merges
*from* master have taken place, it may be too difficult / not worth the
effort to rebase, in which case a "normal" merge is acceptable. However
we should try to keep these at a minimum to avoid cluttering the history.
Thanks for your understanding and consideration.
Damien
PS: I'll add this to the wiki and/or the developer's guide later as time
allows.