Branch Management
From OpenLaszlo
Active development of OpenLaszlo has until recently been done entirely within a Perforce repository that is internal to Laszlo Systems. We have transitioned to a process where development takes place within a Subversion repository that is accessible by any OpenLaszlo community member.
Contents |
Basic Structure
OpenLaszlo's branch management policy mirrors the structure and processes recommended in book "Version Control With Subversion", particularly the Common Branching Patterns section of the Branching and Merging chapter.
The subversion OpenLaszlo repository is available at http://svn.openlaszlo.org/openlaszlo. There is a websvn frontend available here. Instructions for retrieving and building sources can be found at SubversionBuildInstructions.
There are currently four main sub-repositories available under http://svn.openlaszlo.org.
- openlaszlo
- tools - tools that are independent of project or release
- vendor - external (3rd party) tools
- labs - demonstration apps (clockblox, etc.)
Each subrepository (except for vendor) follows the trunk/branches/tags structure described the the svn book. Vendor is a grab-bag of tools which are already versioned and doesn't need the additional structure.
Branching and development process
Locally we make the distinction between a development branch and a release branch. A development branch is used for everyday development, and all submissions should be code-reviewed before commit. A release branch is the staging area for an actual version release, and has a higher bar for changes. The rule is that code is checked in (with a code review) to a development branch, and then integrated (after a public risk assessment) to a release branch. This way every code change that makes its way into a release has been assessed twice: once as part of the code review, and then again as part of the integration proposal process.
There is one development branch per major version under active development. (At the time of this writing there are two: one for 3.x (openlaszlo/trunk), and one for 4.x (openlaszlo/branches/legals).) There is one release branch per minor version (e.g. 3.4), and all incremental releases in that minor version series (e.g. 3.4.0, 3.4.1, etc.) are generated from that release branch.
Code changes should never be directly checked into a review branch, except for the very basic changes necessary to update the version number and build type preparatory to a release. These changes should only be made by the designated release manager.
There is actually a third type of branch, a private branch. This branch can be created for the use of any OpenLaszlo contributor, and is exempt from the usual oversight processes. The usual code review process must be followed when changes are integrated from private to development branch. Changes should never be integrated from a private to a release branch.
Doing Merges
Keeping branches up to date with trunk
Let say you have a branch, 'video', and would like to keep it current with the trunk sources. First, make sure you have a clean, working copy of the destination branch, ie 'branches/video'.
> cd branches/video > svn revert -R . > svn update > svn log --stop-on-copy | grep -i -b2 merge
Now note down the revision number of the last merge, or, if this is the first merge, the revision number of the branch's creation. Also, note the revision number of the most recent change to trunk. Call these R1 and R2, respectively.
> svn merge -r R1:R2 http://svn.openlaszlo.org/openlaszlo/trunk
Look for conflicts in the output, and resolve them as described in the svn book. Do a build, run smokecheck, run other unit tests, make sure everything looks good. Then do a commit.
Important: include rR1:R2 in the commit message! This is how you tell where to start next time you do a merge.
> svn commit -m "Merged trunk changes rR1:R2 into branches/video."
Note: when you merge your branch back to trunk, you will want to omit the revision where trunk was merged to your branch
Re-creating your branch from trunk
Periodically you may want to re-create your branch from trunk. Typically you will do this after you have merged all your changes into trunk and when no one is actively working on changes in your branch. Here's our recommended procedure (continuing the video branch example):
$ svn info -rHEAD URL: http://svn.openlaszlo.org/openlaszlo/trunk Repository Root: http://svn.openlaszlo.org Repository UUID: fa20e4f9-1d0a-0410-b5f3-dc9c16b8b17c Revision: 1247 Node Kind: directory Last Changed Author: ben Last Changed Rev: 1244 Last Changed Date: 2006-07-02 11:51:02 -0700 (Sun, 02 Jul 2006)
Note Revision number
$ svn delete http://svn.openlaszlo.org/openlaszlo/branches/video -m 'about to re-create video branch from trunk' Committed revision 1248.
$ svn copy -r1247 http://svn.openlaszlo.org/openlaszlo/trunk http://svn.openlaszlo.org/openlaszlo/branches/video -m "Recreating video branch from trunk at revision r1247." Committed revision 1249.
