From OpenNMS

Contents 1 Obsolete! 2 Subversion Merging 2.1 Creating a Branch 2.2 Merging Changes 2.3 Committing Your Changes to Trunk 2.4 What Do These Options Mean? 3 Dealing with Stable 3.1 Creating a New Stable Branch 3.2 Fixing Bugs 3.3 Workflow 4 Branches 4.1 General Layout 4.2 Example 4.3 Summary

Obsolete!

This page is obsolete, please see Developing with Git for details on working with the OpenNMS source repository.

It's being kept for historical purposes, some of these techniques should be converted to a Git way of doing things.

Subversion Merging

To manage branches in subversion, we will use the svnmerge.py tool (We're aware that this tool is not necessary with Subversion 1.5, but migrating will mean exporting and reimporting our whole tree, which is not something we want to do right now. It will probably be less painful to migrate to a more modern, distributed system than to migrate to Subversion 1.5.)

Creating a Branch

Svnmerge.py has support for creating feature and developer branches which track changes from other branches. To do so, create a branch like you normally would:

 svn cp -m 'branching for feature <foo>' \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/trunk \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/feature-foo

...and then use svnmerge.py to tell each side to track changes in the other:

 svn co https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/feature-foo
 cd feature-foo
 svnmerge.py init https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/trunk
 svn commit -F svnmerge-commit-message.txt
 cd ../trunk
 svnmerge.py init https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/feature-foo
 svn commit -F svnmerge-commit-message.txt

Merging Changes

To track the current unstable branch in your branch, you just need to tell svnmerge.py to get any pending changes with 'svnmerge.py merge':

 cd feature-foo
 svnmerge.py merge -S trunk
 # <fix any merge conflicts that might have arisen>
 svn commit -F svnmerge-commit-message.txt

Committing Your Changes to Trunk

When your feature is complete and tested/ready to move to trunk, you use 'svnmerge.py merge' much like working in your feature branch:

 cd trunk
 svnmerge.py merge -b -S feature-foo
 # <fix any merge conflicts that might have arisen>
 svn commit -F svnmerge-commit-message.txt

What Do These Options Mean?

-S text (SOURCE) 

It is actually possible to track (through svnmerge.py init) any number of branches. The -S flag tells svnmerge.py which branch you are trying to merge.

-b (BIDIRECTIONAL) 

The bidirectional flag tells svnmerge.py to ignore revisions that the target branch has merged from the source branch. For example, if feature-foo has merged revisions 3, 4, and 5 from trunk, and committed them in the feature-foo branch in revision 8, svnmerge.py will not try to merge revision 8 back into trunk.

Dealing with Stable

Creating a New Stable Branch

When it is time for a release candidate of the next stable release, it will be branched to the branches/ directory in svn in the same way we do feature/development branches (in essence, the "feature" is a stable release) -- for example:

 svn cp -m 'branching in preparation for 1.6 stable' \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/trunk \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/1.6

In addition, we will create a branches/X.X-testing branch which will be used to vet changes before they get released to stable.

 svn cp -m 'branching in preparation for 1.6 stable testing' \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/trunk \
   https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/1.6-testing

Then we'll set up the branches to track each other, much like a feature branch:

 # trunk tracks the 1.6 testing branch, to forward-port bugfixes
 cd trunk
 svnmerge.py init https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/1.6-testing
 svn commit -F svnmerge-commit-message.txt
 
 # 1.6 testing tracks trunk (to allow backporting revisions)
 cd ../1.6-testing
 svnmerge.py init https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/trunk
 svn commit -F svnmerge-commit-message.txt
 
 # 1.6 tracks 1.6-testing (to merge revisions once they've been approved)
 cd ../1.6
 svnmerge.py init https://opennms.svn.sourceforge.net/svnroot/opennms/opennms/branches/1.6-testing
 svn commit -F svnmerge-commit-message.txt

Fixing Bugs

Any issue that is reported against the stable release should be assigned a bug, blocking the next release candidate (which will have a placeholder bug to represent the remaining bugs blocking a release). Bugs can be fixed in trunk, and backported to the X.X-testing branch, or fixed in the X.X-testing branch, and forward-ported to trunk, as appropriate.

When the bug is fixed, you should reference the bug number in the commit message (svn commit -m 'fix for bug #1234, configuration has too much xml') and then the bug should get closed, making a note of the svn revision in the comment.

We will then peer-review any bugs opened against the current blocker bug which are marked CLOSED and not VERIFIED, making additional changes to the code if necessary, and making note of those revisions in the bug. Once the code has been spot-checked and OK'd by an OGP member, we will:

1. merge the specified revisions to the stable branch from the testing branch
   • cd stable-1.6
   • svnmerge.py merge -S 1.6-testing -r rev1,rev2,revN
   • svn commit -F svnmerge-commit-message.txt
2. mark the bug as VERIFIED, making note of the revision committed in the stable branch

When all bugs blocking the placeholder bug are CLOSED and VERIFIED, we will make a new release candidate, and provide a reasonable period of time for users and customers to provide feedback, open new bugs, etc. against the release candidate.

If a release candidate doesn't receive any new non-enhancement bugs in the time determined by the OGP, the release candidate will be re-released as the final version.

Workflow

A typical workflow would be:

1. create a bug
2. commit a fix to the 1.6-testing branch, either directly, or merged from trunk (with a comment referencing the bug that is relevant)
3. mark bug as FIXED (noting the 1.6-testing revision in the bug)
4. someone reviews the pending code
5. upon peer review OK, merge the revision from 1.6-testing to 1.6
6. mark bug as VERIFIED (noting the 1.6 revision in the bug)

Occasionally, we can do "svnmerge.py merge -S 1.6-testing" in trunk to merge any pending bugfixes into trunk. In the meantime, trunk development can continue as it does now, reasonably unfettered and reasonably stable, with major features being developed in a branch to avoid total trunk explosion (TTE).

Branches

General Layout

Our general development goal is to have 2 active "main" branches going at any given time.

• The stable branch, which is the current officially supported for-production-use version of OpenNMS. The branch, and releases based on it, will have a minor version number that is even. (1.2, 1.6, etc.)
• The unstable branch, or trunk, which is the current in-development version of OpenNMS. Releases from this branch will have a minor version number that is odd (1.5, 1.7, etc.)

Each of these branches technically has two branches in subversion, an "anything goes" tree, and a "peer reviewed" tree.

Example

At the time of this writing, OpenNMS 1.6.x is the current stable series. There are 2 1.6 branches:

• 1.6-testing: Anyone with commit access is welcome to commit fixes and minor features to the 1.6-testing branch.
• 1.6: To make changes to this branch, you must commit your change in the 1.6-testing branch, and have a bugzilla bug associated with it which is marked as CLOSED. Any OGP member other than the committer of the change can review it, svnmerge it to the 1.6 branch, and then mark it as VERIFIED in bugzilla.

In the same vein, OpenNMS 1.7.x is the current development series. There are 2 branches targeting 1.7:

• trunk: Anyone with commit access is welcome to commit fixes and major features to trunk. It is recommended that features be developed on a feature branch until unit tests pass and it's ready to merge into trunk.
• 1.7: To make changes to this branch, you must commit your change in trunk. Any OGP member other than the committer of the change can review it and svnmerge it to the 1.7 branch. Changes to the development series do not need associated bugs, but it is recommended that new features have an associated enhancement-level bug.

Summary

	Branch	Purpose	Tracks Changes In...
least stable	opennms/branches/feature-<featurename>	new development, architectural and large-scale changes	Y.Y
	opennms/branches/Y.Y	peer reviewed changes for trunk (released as snapshots)	trunk
	opennms/trunk	new development, obvious code changes	feature-<featurename> (for merging a completed feature to trunk) X.X-testing (for merging bugfixes to trunk)
	opennms/branches/X.X-testing	bugfixes, pending peer review	trunk (for backports)
most stable	opennms/branches/X.X	bugfixes, peer reviewed and merged from X.X-testing	X.X-testing (for merging peer-reviewed code)