Branching and merging strategy

Big questions:

• What do all the branches mean?
• What is our schedule and flow for merging branches?

Development happens on multiple branches in parallel. We have multiple types of branches:

• The master branch: Publicly released, production-ready code that will be installed by end users.
• "Release" branches: Branches that are being prepared for release, but not yet public.
• "Project" branches: Branches in development for particular pre-release projects, such as partner deployments.
• The develop branch: Very in-progress, potentially buggy code, to be released in a longer time window.

These branches are arranged in a roughly linear sequence, to simplify our merge/release strategy: develop, project, release, master. This means that when code is ready to be moved closer to production, we do a "forwards merge" along the direction of this chain. We also do "backwards merges" on a regular basis to bring changes (e.g. hotfixes) from the more public branches back into the development branches. Backwards merges can happen any time, but at least once a week (currently scheduled for Mondays).

Choosing where to branch off from and target a pull request depends on an assessment of three factors: how urgent the fix/feature is, how risky (in terms of introducing other bugs) the required changes are, and how long it will take to develop. A good heuristic is to see how urgent the code you're committing vs. how risky or potentially breaking it is:

      Master     Release                 Projects     Develop
    <-------------------------------------------------------->
      More urgent                                 More risky

For example, a critical hotfix that involves a small, low-risk code change should branch from and target back to the master branch, whereas a more involved, and simply "nice to have", feature should target the develop branch.

Here is a further breakdown of the type of fixes that will go to each branch, and the general flow of the code with the implemented merge strategy:

Master (hotfixes)
---->\
      \    Release branches 
       \   (noncritical fixes, 
        \   short-term public features)
         ->-------->\
                     \
                      \   Project branches
                       \  (project-specific features)
                        ->------>\
                                  \   Develop
                                   \  (long-term public features)
                                    ->------>