[mantisbt-dev] Git "Spaghetti" history

[Damien R. <dr...@ma...>]

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.