[commits] [Wiki] changed: Doc/Dev/Branches

[Jan Schneider]

jan  Sat, 02 Jul 2011 14:47:59 +0000

Modified page: http://wiki.horde.org/Doc/Dev/Branches
New Revision:  2.0
Change log:  Outline of a branching model

@@ -1,12 +1,62 @@
  + Branch management

-(First draft, already superceded)
+We follow a branching model that is a very simplified version of  
http://nvie.com/posts/a-successful-git-branching-model/. The main  
difference is that we do bug fixing and make releases from the  
//master// branch, and only use release branches for older, still  
maintained versions. It is suggested to read this post first, to get  
an larger view on the ideas behind our branching model.

-We will actively maintain 3 development branches in Git:

-* Main development for the next release happens in the **master** branch.
-  * Only when the release process starts, we will branch off  
**master**, so that we can stabilize the code for the next release,  
while still going forward with development in **master**.
-  * Major, especially BC breaking changes will be done in **topic  
branches**, to not have the **master** branch polluted with unstable  
code when the next release cycle arrives.
-* The most recent two **major version branches** will be maintained  
with security fixes.
+++ Main branches

-If for example we already had 4.0, 5.0 and 5.1 releases and are now  
working on the 6.0 release, we would maintain FRAMEWORK_4_0,  
FRAMEWORK_5_1 and master branches. Once 6.0 is released, we maintain  
FRAMEWORK_5_1, FRAMEWORK_6_0 and master branches.
+There are two main branches, //master// and //develop//.
+
+- //master// is the branch for adding bug fixes. This is the code  
that will become the next bug fix release.
+- //develop// is the branch for adding new features. This is the code  
that will become the next major or minor release.
+
+//develop// has been branched off from //master// at one point, and  
from time to time, bug fixes that have been applied to //master// are  
merged back into //develop//:
+
+<code>
+$ git checkout develop
+$ git merge master
+$ git push
+</code>
+
+It is suggested to do that merging and pushing in a single, separate  
action, so that "real" work on the //develop// branch isn't get lost  
in the large commit messages of the merging.
+
+
+++ Topic branches
+
+Even though //develop// is the branch for new development and adding  
features, larger features should be developed in a topic branch that  
is branched off //develop//:
+
+<code>
+$ git checkout develop
+$ git checkout -b newfeature
+</code>
+
+This is to avoid breaking code in //develop//. This is important,  
because //develop// is used for the next minor release, which will be  
created at a set date. To avoid having to revert commits if  
//develop// is unstable when the next release is near, such  
development must be done in topic branches, that can be merged back to  
develop, once they stabilized:
+
+<code>
+$ git checkout develop
+$ git merge newfeature
+$ git branch -d newfeature
+</code>
+
+These topic branches can be private, or public if other should  
participate in development or testing. For creating public branches,  
see  
http://www.horde.org/development/git#creating-managing-remote-branches.
+
+Topic branches are especially important when developing code that  
breaks backward compatibility, if it has **not** been decided yet  
whether the next release will be a major or minor release.
+
+
+++ Release branches
+
+Release branches are maintenance branches for older releases. Once  
the release process for a new minor/major version is starting, the  
current version's code is branched off //master// into a release  
branch, before the current //develop// branch is merged back into  
//master// for the new version:
+
+<code>
+$ git checkout master
+$ git branch FRAMEWORK_4_0
+$ git merge develop
+</code>
+
+Since we always ((Doc/Dev/ReleaseCycle|maintain the two most recent  
minor versions)) with security fixes, there will always be 3 active  
branches (topic branches aside) at the same time. //master//,  
//develop//, and the release branch for the last minor version.
+
+If for example we already had 4.0, 5.0 and 5.1 releases and are now  
working on the 6.0 release, we would maintain //develop//, //master//  
and //FRAMEWORK_5_1// branches.
+
+++ Tools
+
+[gitflow https://github.com/nvie/gitflow] is a tool for managing the  
branching model of Vincent (nvie). If necessary, we might be able to  
fork and adapt it to our simpler needs.