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 is only one: for 4.x.) There is one release branch per minor version (e.g. 4.2), and all incremental releases in that minor version series (e.g. 4.2.0, 4.2.1, etc.) are generated from that release branch. Occasionally, there will be 'point' releases finer than the incremental release. As long as the point releases are at the 'head' of the branch no further branching is needed. If for some reason a point release is needed for an earlier minor release, a separate branch for that minor release can be created from the tag for that release.
Code changes should never be directly checked into a release 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.
Creating a Branch
This example supposes that trunk is the active development branch for the 4-series of releases and that you are creating the 4.2 release
Branch
svn cp http://svn.openlaszlo.org/openlaszlo/trunk http://svn.openlaszlo.org/openlaszlo/branches/4.2
Get a working copy
mkdir 4.2
cd 4.2
svn co http://svn.openlaszlo.org/openlaszlo/branches/4.2 .
Set up merge tracking
We use svnmerge.py to handle merge tracking between a branch and it's parent.
a) find where you branched, b) use svnmerge init to note that, c) check that in
[ptw@dueling-banjos 4.2.0 16:24:23]$ svn info Path: . URL: http://svn.openlaszlo.org/openlaszlo/branches/4.2.0 Repository Root: http://svn.openlaszlo.org Repository UUID: fa20e4f9-1d0a-0410-b5f3-dc9c16b8b17c Revision: <Ignore this Number> Node Kind: directory Schedule: normal Last Changed Author: ptw Last Changed Rev: <Note this Number> Last Changed Date: 2008-12-17 14:09:19 -0500 (Wed, 17 Dec 2008) Properties Last Updated: 2008-12-17 14:12:05 -0500 (Wed, 17 Dec 2008) [ptw@dueling-banjos 4.2.0 16:24:40]$ svnmerge init -r 1-<Put That Number Here> --force property 'svnmerge-integrated' set on '.' [ptw@dueling-banjos 4.2.0 17:24:31]$ svn ci -F svnmerge-commit-message.txt ...
Set up merge tracking from the new branch back to trunk too:
cd ../trunk
svnmerge init -r 1-<Put That Number Here> ../4.2
svn ci -F svnmerge-commit-message.txt
Update versions.xml
Update versions.xml in the branch. You will want to integrate your changes back to trunk, just for posterity. If this is a new branch, you will have to create a new <branch> and <entry>. Each <entry> maps the svn revision in the branch to a release and id. The id is the "marketing" version, typically a 3-part numeric version. We specify a point release of 0 initially.
<branch url="http://svn.openlaszlo.org/openlaszlo/branches/4.7"> <entry revision="15428" release="RC" id="4.7.0" />
The options for release are:
- Latest
- for nightly builds
- RC
- for Release Candidate
- Production
- only for shipping
The build system will use the last entry whose revision is greater-than or equal to the revision being built (typically the latest revision in the branch), so you typically will use the current revision + 1 to identify a release. If you are creating a production release, you should add two entries, one identifying the production release, and a second that will cause any further changes in the branch to be associated with the next point release (if any):
<entry revision="15482" release="Production" id="4.7.0" /> <entry revision="15483" release="Latest" id="4.7.1" />
You should integrate version.xml back from the branch to trunk and also update the entries for trunk to the next planned release:
<branch url="http://svn.openlaszlo.org/openlaszlo/trunk"> <entry revision="15440" release="Latest" id="5.0.x" />
Add the branch to nightly-go
Edit nightly-go.sh, adding a case for the branch you created. The contextpath indicates where the build will be deployed on Labs. If you are creating a new context path, IT will need to update the webserver configuration to support it.
Index: nightly-go.sh
===================================================================
--- nightly-go.sh (revision 14345)
+++ nightly-go.sh (working copy)
@@ -91,9 +91,13 @@
case ${branchmunge} in
# Default settings for trunk
"trunk")
contextpath="/trunk-nightly"
;;
+ "branches-4.7")
+ contextpath="/lps-4.7-nightly"
+ ;;
Update the build machine
Log in to the build machine
- Update the tools:
> (cd src/svn/tools/trunk/; svn up)
Update labs.openlaszlo.org
Ask IT to add a JKMount directive to /etc/httpd/conf.d/openlaszlo.conf mapping the nightly builds of the branch:
JkMount /lps-4.4-nightly/* labs JkMount /lps-4.4-nightly labs
Kick off a build for your branch
> source ~/src/svn/tools/trunk/env/setup-lps.sh > nohup ./nightly-go.sh branches/4.2 &
- Wait for the mail, deal with issues... Lather, rinse, repeat.
Creating a "Point Release"
If you are making incremental patches to a branch, (i.e., incrementing the 3rd component of the branch version/release number, which we some times refer to as a "point release"), you will not create a whole new branch. In this case, you simply update versions.xml (in the branch, and integrate back to trunk). CAUTION: In releases after 4.2, OBI-60 at least has a stop-gap that will fail the build immediately if you screw this up. If you are trying to build an earlier release, you just have to get it right, or you will only discover your error when you try to actually install and run the build...
As noted above, if your are creating a production build, you will want to update the versions.xml to also include a `release = Latest` and the next point number, just in case there will be a subsequent point release.
Integrating changes to a branch
Since most branches are created for (eventual) release, here we describe the release policy. If you have created a private branch for your own development, you are obviously free to manage that in any way you like:
Propose your change for integration
Send email to Laszlo-Dev proposing that your change (which has presumably already be reviewed and tested in the development branch) be integrated to the release. The exact criteria for a change to be integrated into a release branch will be set by the release manager. Typically, only bugs reported by QA or beta testers, or bugs that can be show to potentially affect many users will be candidates for integration to a release branch. The closer the branch is to a final release, the stricter these criteria will be.
As an example, you should enumerate the benefits and risks of your change.
- Benefit-side:
- Is this a show-stopper?
- QA-reported bug?
- Something everyone will run into?
- Risk-side:
- How large is the change?
- Could it have affected some other part of the system?
Wait for approval.
Mark your change for integration in Jira
Assuming the community and branch manager agree to your proposal, re-open the bug your change fixes in Jira, mark it as needing to be fixed for the branch in question, and assign it to the branch manager for integration.
Integrate the change
The branch manager integrates the change using svnmerge (which was set up when the branch was created):
> svnmerge merge -b -r<trunk revision of your change> -S trunk
If you are trying to merge from trunk into the branch, then you should execute this command from the branch. If you are merging from a branch into the trunk, you should execute this in trunk.
If the merge is not straightforward, e.g., if there are conflicts, the branch manager may ask for your help in resolving them (or may even assign the task to you). This is not likely to be an issue for current releases, but changes that are migrated back to legacy releases may even need a completely different implementation. In that case, you will not use svnmerge, you will have to develop the solution in the legacy branch, and do a normal [Review].
Verify the change
At the very least, you should inspect the differences the integration created to ensure they are what you intended. If your change is risky, you should consider making a local build and testing.
Check in the change
> svn ci -F svnmerge-commit-message.txt
Update Jira
Note the svn revision number of your change, and use
> svn log -v -r<svn revision number>
to get the check in message. Resolve the bug, noting the revision number of the integration, paste the log from above as a comment, and set Fixed in branch to the appropriate branch.
Start a build
If you are not expecting any more integrations for a while, you will want to start a build of the branch for testing.
