[waffle] Branch and merge strategy

[Chad Versace]

If you are a contributor and want one take-away message from this email,
it is:

    Continue to send patches and merge-requests to the mailing list. If
    in doubt, you should target the 'master' branch. If it's a bugfix,
    consider targeting one of the maintenance branches instead, but
    'master' is ok too.

If you don't care about Waffle's branching strategy, you can stop
reading now.

After releasing 1.5.0, here's the status of the various branches:

    - master
        It's master. What more can I say? I try to ensure that patches
        land on master only if they're already proven stable on some
        integration branch (or if they're obviously safe).

    - maint-1.4
        This branch is still alive. Future 1.4 maintenance releases
        will continue to be tagged off this branch. When people stop
        caring about 1.4 release, I will delete this branch. (The 1.4
        tags, however, will not be deleted).

    - maint-1.5
        This branch forked from master at the v1.5.0 release tag. Future
        1.5 maintenance releases will be tagged off this branch.

    - maint
        I deleted this unversioned maintenance branch, because I feel
        that *explicitly* versioned maintenance branches are better
        because and reduce confusion.

    - next
        "'master' should always be stable and be in a releasable state".
        Google projects and Git try to adhere to that mantra, and
        I respect that. I'm trying to follow that precedent now with
        Waffle.

        To ensure that 'master' is stable, I'm following the example of
        the Git project by maintainig an integration branch named 'next'.

        If a patch or patch series looks good good and appropriate for
        master, but poses some stability risk, then I first merge the
        patches to 'next'. After the patches have baked on 'next' and
        I feel confident they don't pose too much of a stability threat,
        then I merge the patches to 'master'.

        After releasing 1.5.0, I rewound 'next' onto 'master' to "give
        it new life" and make the branch history easier to understand. All
        commits were already in master, though, so now next == master.
        I'll rewind this branch onto master again when next feature
        release happens (1.6.0).

If you've been following along the git history, you may have noticed
that Waffle's history is no longer linear. In Waffle's branching and
merging strategy, I'm trying to follow some precedence established by
the Git project and documented in man:gitworkflows(7)
[https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html]

Below is a short summary of how I'm handling branching and merging in
Waffle. It heavily borrows from man:gitworkflows(7), but is a bit
simpler (there is no 'pu' branch, for example). It's a lot of verbage,
but (at least from the maintainer's perspective) it's a very intuitive
workflow.

    - Merges are preferred over cherry-picks.

      From git:workflows(7):

        There are two main tools that can be used to include changes
        from one branch on another: git-merge(1) and git-cherry-pick(1).

        Merges have many advantages, so we try to solve as many problems
        as possible with merges alone. Cherry-picking is still
        occasionally useful; see "Merging upwards" below for an example.

        Most importantly, merging works at the branch level, while
        cherry-picking works at the commit level. This means that
        a merge can carry over the changes from 1, 10, or 1000 commits
        with equal ease, which in turn means the workflow scales much
        better to a large number of contributors (and contributions).
        Merges are also easier to understand because a merge commit is
        a "promise" that all changes from all its parents are now
        included.

        There is a tradeoff of course: merges require a more careful
        branch management. [...]

    - If the git history contains frequent cherry-picks, then the
      workflow isn't working well for Waffle or the workflow isn't being
      used correctly.

    - If a contribution consists of a single patch, then the patch gets
      committed directly to the oldest branch for which that patch makes
      sense.  If it's a fix, then it gets committed to a maintenance
      branch. Otherwise, it gets committed to 'master' or an integration
      branch.

    - If a contribution conists of multiple patches, the patch series
      gets merged as a topic branch to the oldest branch for which that
      patch series makes sense. If it's a fix, then it gets merged to
      a maintenance branch. Otherwise, it gets merged to 'master' or an
      integration branch.

    - To improve readability of the git history, topical merge commits
      should be titled as
          Merge '$AUTHOR_HANDLE/$DESCRIPTION'
      For example,
          Merge branch 'evelikov/remove-libgbm-libgl-libdeps-v2'

    - All branches are periodically merged "upwards".

          maint-1.4 -> maint-1.5 -> master -> next

      Merging maintenance branches upwards guarantees that all fixes
      exist in the branches where they're needed.

    - To improve readability of the git history, the periodic "upward"
      merges should be titled as
          Merge '$SRC' into $DEST
      For example,

          Merge 'maint-1.4' into master

    - Branches are *never* merged downards.

          NEVER: master <- next

    - History on 'master' and the maintenance branches is never
      destroyed. (No rebase, no force-push).

    - When commits need to travel "downwards", against the normal
      "upward" branchflow, such as

          maint-1.4 <- (important-fix) <- master

      or

          master <- (new-feature) <- next

      Then the commits are either cherry-picked downwstream. Or the topic
      branch is rebased onto the downstream branch and merged. Whatever
      strategy is appropriate for the situation.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 884 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/waffle/attachments/20141210/45ab9018/attachment.sig>