[Scummvm-devel] merging

[Willem Jan Palenstijn]

Hi all,

After some IRC discussion about the merits of rebasing and merging in git
recently, I've written up some notes/suggestions on the topic below.

Any comments? Additional good advice? Different opinions?


Something I'd like to discuss further before even starting to write it down:
Are there any specific cases where we should encourage squashing before
merging? I'm thinking of things like accidentally committed files/directories,
mass renames, unintended broken builds, savegame incompatibility, commits
immediately followed by typo fixes/minor bugfixes, ...



-Willem Jan



----

One line summary: Don't rebase branches just to avoid merges.

This applies both during development of a topic branch and when pushing it to
master, including for github pull requests.

While rebasing does make a branch's history seem cleaner, it requires
significant effort to ensure rebasing doesn't break the history. Some forms of
broken history are easily detected because they break the build, but others are
much more subtle.

Also, merge commits are a useful place to put a summary of changes introduced
in a set of commits. You should even consider adding a merge commit for this
purpose even if the merge would otherwise not need one. A particular case where
this could be valuable is if for some (preferably very good) reason you
temporarily need to break the build: follow up the "broken build" commits with
a merge commit as a clear way to mark them.

There are of course cases where a rebase does indeed clean things up, and for
small sets of changes this is definitely worth considering.

In general, apply common sense. This document should only be considered a
guideline, since for any rule there will be exceptions. Feel free to ask on the
mailing list or on IRC at any time about what would be appropriate in any
specific case.


Historical context:

When we switched from subversion to git, we initially had a preference to use
rebasing to avoid merge commits, because those felt unnecessary or ugly. After
working with git for a while as a project, the disadvantages have started to
become more clear, to the point where we now generally prefer merges.