How to branch and merge properly

Branching

• As far as possible/reasonable, keep one branch per topic
• Try to make an extra effort to keep one commit per (unrelated) change
• Try to make an extra effort to use a good commit message
• Please rebase at least once when you are close to merge time
• Consider squashing your commits:
  • Following a myriad commits with slight changes, especially when commit 3 partially modifies commit 1, is hard
  • Combine all related commits that implement sensible and easy-to-understand changes in one commit
  • But do not squash all your changes together! Only when it makes sense

In doubt? Just ask.

Merging

tl;dr

• Multiple commits? Pull target branch, rebase PR branch, push, click "Create a merge commit"

• Single commit? Use "Rebase and Merge"

• Only if the PR author is the same person merging the PR:

  Just want to squash all commits into one? Use "Squash and Merge"

In doubt? Use gitk to take a look.

Reasoning

• if we need to merge a single commit, or commits which can be squashed into one single commit (ie. cases in which history is very limited or irrelevant), we do not want an extra merge commit
• otherwise, we want:
  • the topic branch to be rebased to the latest branch we are merging into (master, 4.0, etc.) in order to simplify history and help git bisect to work better
  • the merge to happen in "non-fast-forward" mode, that is retaining the merge commit. Difference is explained below:

Note that using the "non-fast-forward" mode:

• creates a visual grouping of commits that were created together
• allows one-commit revert by reverting the merge commit

Good Guy Example

Bad Guy Example