Views
Branching and Subversion
Branching is very straightforward in subversion, but merging is not. Be sure to follow these guidelines to assure consistent and safe branches and merges.
Merge Tracking and Subversion
What's Missing?
The first merge to/from a branch is pretty easy since the start of the branch is a convenient revision boundary. However, Subversion does not track mergepoints, so it is necessary to manually derive previous mergepoints when performing subsequent merges.
Something That Works
The current strategy is to use Svnmerge to perform merge tracking. Once the Mifos Subversion repository server is upgraded to version 1.5 or later, using Svnmerge will no longer be necessary.
Please download and use the "svnmerge.py trunk version".
HOWTO
Development
Development branches are typically created to fix a specific bug or add a new feature without affecting mainline development.
Creating a Development Branch
When branching the Mifos source code, always branch the entire trunk and always copy to a directory in the branches directory.
Initialize Svnmerge by executing svnmerge init in the branch directory as mentioned in the Svnmerge manual.
Naming Convention
- If the branch is related to an issue, the name of the branch should be issue_XXXX, where XXXX is the issue number. Example: issue_1339.
- If the branch has no associated issue but does have a story in Mingle, story_XXXX.
- If the branch spans multiple issues, a branch name should be discussed and agreed upon via IRC and/or the developer listserv.
Merges to the Development Branch
Execute svnmerge merge in the branch directory as mentioned in the Svnmerge manual.
Here's a brief walkthrough:
- Clean up your working copy. That means commit any modified/added/deleted files or directories.
- Perform an SVN update to make sure your branch is up to date.
- Execute svnmerge merge.
- Resolve any merge conflicts as per standard SVN practice.
- Execute svn commit -F svnmerge-commit-message.txt. The commit may be performed from within a SVN GUI frontend like Subclipse or TortoiseSVN, just make sure you use the exact contents of svnmerge-commit-message.txt as your commit log message.
- Remove svnmerge-commit-message.txt.
This whole procedure should be one changeset. Don't change any files or directories in the working copy between the "merge" and "commit" steps.
Releases
Release branches are created to be able to support particularly important patches (security fixes, etc.) from mainline development, while ignoring others.
Creating a Release Branch
Follow steps for creating a development branch.
Naming Convention
- A "major" release branch: v1.x. This branch would be created so 2.x work could commence on the trunk, for example.
- A "minor" release branch: v1.1.x. This branch would be created so 1.2 work could commence on the trunk, for example.
Merges to the Release Branch
Follow steps for performing a development merge, cherry picking as necessary according to the Svnmerge manual.
Tagging
Because of the nature of global revision numbers in Subversion, tags are not necessary. However, it can be convenient to create tags in order to provide a friendlier name.
Ad-hoc tags should be created sparingly.
Release tag example: for the version 1.2.1 release, branches/v1.2.x would be tagged at tags/v1.2.1.
Mifos Version 1.1
The branch/merge plan for version 1.1 will serve as a practical example of how to manage a release branch. This plan is largely adopted from "Release Branches" in Producing Open Source Software (Fogel, O'Reilly Media, 2007).
Stabilizing the Release Branch
A release branch will be created on 30-JUN-2008 at:
https://mifos.dev.java.net/svn/mifos/branches/v1.1.x
This will allow work on v1.2.x to continue on the trunk.
The branch will be stabilized by applying only isolated bugfixes and security updates. If possible, a given fix will first be applied to the trunk, then merged to the branch. If the trunk and the v1.1.x branch diverge to the point where this is not possible, the fix will be committed directly to the branch, then manually ported to the trunk.
Mifos version 1.1 will simply be a particular revision of the v1.1.x branch that has been tested and agreed to be the revision to be built from and released. Once this revision is known, it will be tagged at:
https://mifos.dev.java.net/svn/mifos/tags/v1.1.0
The release package will be built from this tag. Subsequent point releases (if any) will be named 1.1.1, 1.1.2, etc. and tagged similarly.
Note that version "1.1" will exist in the repository as "1.1.0".
Branch Lifetime
The v1.1.x branch will be maintained with bugfixes and security updates until a v1.2.x branch is created.
Mifos Version 2.x
Once work is ready to commence on version 2.x, all version 1.x development can be moved to a new branch
https://mifos.dev.java.net/svn/mifos/branches/v1.x
This will effectively become the "mainline" for ongoing 1.x maintenance. The trunk would then be used for version 2.x development.