Recommend using rebase with merge commit for a cleaner version tree

[damithc]

In cases like this, 'rebase with merge commit' can give a cleaner version history (i.e. avoid 'wire crossing'). Unfortunately, GitHub doesn't have such an option so we have to do it ourselves.

[wkurniawan07]

In rebase workflow, there is no concept of "merge" in the first place, much less a "merge commit". Rebasing makes sure the history is perfectly linear.

But to make full use of rebase workflow, the commit message practice needs to change. This workflow is one that is very independent of the concept of "GitHub issues": every single commit can be fully reasoned on its own (in ideal case). [1234] Issue title is no longer a meaningful commit message in a perfectly linear history.

To tell if some commit resolves a certain issue, it's usually the last part of the commit message:

Commit summary

Further explanation of commit ...
...

Let's do this ...

Fixes #1234

Or, if there are multiple commits, the commit message except for the last commit shall be:

Commit summary

Further explanation of commit ...
...

Let's do this ...

Reference: #1234

To make full use of this workflow, everyone must be fully confident of rebasing and its more advanced concepts such as squash, fixup, edit, etc. and the rule must be strict; a misplaced Fixes would have ruined the history already.

Add:

• An advantage of rebase workflow is its full support for partial fix. One can simply use Reference: #1234 to tell that some issue is referenced, and the fact that it is not Fixes will tell that the fix is partial.
• Using the above workflow would also mean that Fixes #1234 is no longer relevant to be put in the PR, other than for the sake of adding an issue-PR reference. This further shows how the workflow is independent of the concept of GitHub issue and PR.
• Even better: this workflow fully supports PRs without issues -- by simply omitting the Reference: #1234 or Fixes #1234 part.