WTP How to: Branching Policy and Practices

This page is to capture issues, best practices and pragmatic information on how to work with branches in WTP Development. This includes how and when developers should branch, and how other committers and members of the community can discover which branches they need load into their workspace so it matches a particular build or development stream.

Issues and Problems with WTP Branching

These are some of the main issues to consider.

• WTP Projects (and components) should have the flexibility to do branching as they decide, using what ever works best for them, their team's workflow, and habits.
• But, we need to make it easy for others to know what to load in their workspace, to match any particular stream or build.
• And, we need to avoid those silly bugs or build breaks where the wrong branch of code is released to the wrong branch of a map file.

There can be complicating factors

• Each team is usually doing something different from other teams; focusing on maintenance versus focusing mostly on future development.
• There are probably some bundles that will not change much in either stream, others may change a relatively large amount in both streams.

Solution

There are several ways to accomplish what we need, and the difference between them are how they balance the issues above. (That is, none are perfect).

On one extreme, we could just say we'll branch everything at once so it's clear what to get, and where to do work. The concern is that this will be more work for developers ... error prone work, at that. The extra work to ensure bugs fixed in maintenance get rolled up to the HEAD stream. Tools could help, but some have expressed less that stellar success with merge utilities.

On the other extreme each team could do branching on a plugin-by-plugin basis, as they found a need to. This would be easiest for those actively working on the code, but not easy for other committers from other WTP teams, and certainly not the community at large! Plus, this method would be prone to the error of releasing into the wrong map, since easy for mis-matched bundles to end up in the same workspace, in the same map.

So, I propose a compromise between the two extremes, something larger than a plugin, but smaller than everything. A "feature" might be one such branching unit, but there are no tools oriented towards CVS and features. Therefore, I suggest we use the map files as the operational "unit of work" when making or getting branches.

To give a concrete example, if someone was to make a 3.1-only change in the xml.core plugin, then at that point, besides just branching xml.core plugin, all the other bundles listed in wst-xml-core.map must be branched also, namely sse.core, xsd.core, and dtd.core. This would help make sure bundles of a map stayed together as a branch, making mis-released code more unlikely.

And, on the other hand, if not much new work was going on in, say, the xml-ui plugins, they would not have to be branched, so any bugs fixed there would be expected to be released twice, using exact same cvs tag version, into both branches of releng maps. The importance of using the same cvs tag version is that the cvs version tag becomes, or contributes to, the bundles qualifier field. Ideally, when two bundles are exactly the same, even though in different builds, then they have the exact same version number, down to the qualifier. This helps others (and automated tools) to know that they are the same code. Note: in some cases, the releng "release tool" still works as expected if you specify an existing cvs version ... it still updates the map files correctly and does not throw an error that "tag already exists". But in other cases not. Not sure what the differences are (how branched, perhaps?) ... but, is often easier to release to maintenance branch of map files, and then "manually" merge the maintenance map file versions into the HEAD version of the map files -- when the code being delivered to each build is identical, that is.

In many cases, the map files correspond to the distinct build-component-features we use, so, conceptually this is the same as the branching feature by feature.

Of course, there is no need to specifically limit branching to only one-map-file-type of branching, that's just the "minimum unit" of bundles that should be branched together. Some teams, components, or projects may want to branch all their project code at once, for example, so as long as each map file, as a whole, has all it's bundles branched together, then that is fine.

Practice

• The releng projects for the map files, are always branched for maintenance, using conventions in the branch name such as R3_0_maintenance, R2_0_maintenance, R1_5_maintenance, etc. The HEAD stream of releng is always used for the most forward looking release.

• The best way to create a branch is to first of all use the same naming convention as used in the releng map file project: that is, for example, use the name R3_2_maintenance for much of WTP, though other projects would use their specific version, such as R1_2_maintenance for JSDT code. Second, for consistency and easy of figuring it our later, the "starting tag" is best left as the default suggestion in the branching wizard. For example, when you create R3_2_maintenance for a bundle, you should use Root_R3_2_maintenance. The R3_2_maintenance version tag might be different than the R3_2_0 version tag created at previous release, but that normally doesn't matter.

• The map file itself should identify, in file comments, the branch that the bundles in that map file come from. This way, when someone loads the releng map project for a certain release, they can "drill down" in the map files to see what branch they should load from, for a particular area of code. For example:

!*************** wst-xml-core.map

! This map file is for 
! WTP 3.0.x maintenance releases  

! These bundles are currently being developed and released 
! from the HEAD stream

plugin@org.eclipse.wst.dtd.core=v200705302225,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/dtd/plugins/org.eclipse.wst.dtd.core
plugin@org.eclipse.wst.sse.core=v200706212223,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/sse/plugins/org.eclipse.wst.sse.core
plugin@org.eclipse.wst.xml.core=v200706120811,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/xml/plugins/org.eclipse.wst.xml.core
plugin@org.eclipse.wst.xsd.core=v200707172046,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/xsd/plugins/org.eclipse.wst.xsd.core

!*************** 

Or, for example,

!*************** wst-xml-core.map

! This map file is for 
! WTP 3.0.x maintenance releases  

! These bundles are currently being developed and released 
! from the R3_0_maintenance branch
 
plugin@org.eclipse.wst.dtd.core=v200705302225,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/dtd/plugins/org.eclipse.wst.dtd.core
plugin@org.eclipse.wst.sse.core=v200706212223,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/sse/plugins/org.eclipse.wst.sse.core
plugin@org.eclipse.wst.xml.core=v200706120811,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/xml/plugins/org.eclipse.wst.xml.core
plugin@org.eclipse.wst.xsd.core=v200707172046,:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools,,wst/components/xsd/plugins/org.eclipse.wst.xsd.core

!*************** 

Tips

• Normally, a project or component team will know when the bundles in a map file have been branched, through the wtp-releng mailing list, or hallway talk. Nevertheless, when releasing code, it's good practice to expand the changes to the map files, there you can double check that the branch you have been working with are still the same branch that is appropriate. If not, the release should be canceled until the branches in your workspace are synch'd up correctly.