HOWTO: Branching, Merging

Client Software Versions

Any of Subversion, TortoiseSVN, or Subclipse should work for merging as long as the version is 1.6.x or later. Do not use Subclipse.

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. While this document assumes all branches originate from trunk, it is of course possible to branch off other branches (with the proper amount of team communication and coordination).

It's fine to check broken code, TODOs, etc. into your branch. That's your sandbox, do what you will. Only when you want us to merge to the trunk do you need to make sure that the patch (collection of changes to be merged) is vetted

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 mailing list

Merges to the Development Branch

If you are working on a development branch, you are responsible for merging in trunk changes frequently. We recommend merging before starting work each day. If you notice a commit on the trunk that may conflict with your work, merge sooner rather than later!

Merge (sync) trunk changes into your branch working copy. This howto assumes use of the command-line svn client, but other clients (such as TortoiseSVN and Subclipse) may also be used to perform merges.

Here's a brief walkthrough:

1. Clean up your working copy. That means commit any modified/added/deleted files or directories.
2. Perform an SVN update to make sure your branch is up to date.
3. Merge in the latest trunk changes.
4. Resolve any merge conflicts as per standard SVN practice.
5. Commit, with a helpful commit log message

This whole procedure should be one changeset. Don't change any files or directories in the working copy between the "merge" and "commit" steps except to resolve conflicts.

Merges back to trunk

Notifying trunk maintainers

Developers working on branches are responsible for proactively notifying trunk maintainers when their changes are ready to be merged to the trunk.

When you are ready for your branch to be merged back into the trunk (ie: every changeset on your branch that hasn't already been merged to the trunk) just cut and paste the phrase:

Please merge all branch changes onto the trunk.

in your commit log message. If you want only a particular revision merged into the trunk, use:

Please merge this revision onto the trunk.

If you know that a particular change should never be merged into the trunk:

Please block this revision from merging onto the trunk.

It would be best if these phrases were on a line by themselves. If you mess up a commit log message, no problem, just give us explicit merge or block instructions on IRC or the mifos-developer mailing list. But if we do use the above procedure for communicating, we'll be encouraged to follow commit emails/feeds closely and can even use scripts to watch for these phrases.

The criteria in VettingPatches must be met prior to submitting a merge request.

Branch Lifetime

Development branches should have relatively short lifetimes.

From the book:

In Subversion 1.5, once a --reintegrate merge is done from branch to trunk, the branch is no longer usable for further work.

If the branch is still desired after reintegration, it can be re-created.

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

• branches/v1.1.x. This branch would be created so, for example, version 1.2 work could commence on the trunk.

Merges to the Release Branch

Follow steps for performing a development merge, cherry picking and blocking as necessary according to the Svn 1.6 manual.

Merges back to trunk

While trunk bug and security fixes may be merged into release branches, changesets on release branches are generally not merged back to the trunk. Expect changes to flow one-way. If you have to fix a bug in a release, fix it first in the trunk, then merge it into the branch. If you can't merge it into the branch, port it to (rewrite it on) the branch.

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.

Miscellaneous tags

Ad-hoc tags should be created sparingly.

Release tags

Release tag example: for the version 1.2.1 release, branches/v1.2.x would be tagged at tags/v1.2.1.

Release Branch Example: 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

Release branch example:

https://mifos.svn.sourceforge.net/svnroot/mifos/branches/v1.1.x

This allows work on the next release (probably v1.2.x) to continue on the trunk.

The branch is stabilized by applying only isolated bugfixes and security updates. 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 if necessary.

Mifos version 1.1 is simply 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 is tagged at:

https://mifos.svn.sourceforge.net/svnroot/mifos/tags/v1.1.0

The release package is built from this tag. Subsequent point releases (if any) are named 1.1.1, 1.1.2, etc. and tagged similarly.

Note that version "1.1" exists in the repository as "1.1.0".

Branch Lifetime

The example v1.1.x branch will be maintained with bugfixes and security updates until a v1.2.x branch is created.

Troubleshooting

Working copy out of date

When trying to commit a merge, you may see an error like this:

svn: Commit failed (details follow):
svn: Your file or directory '.' is probably out-of-date
svn: The version resource does not correspond to the resource within the transaction.
Either the requested version resource is out of date (needs to be updated), or the
requested version resource is newer than the transaction root (restart the commit).

Try performing an "svn update", then run the commit again. If no conflicts are found after the update, the commit should then succeed.

Mid-merge conflicts

See the warning starting with Did you notice how... in the manual.