Releasing and Patching

Overview

The purpose of releasing is to share your suite or module with scientists. The purpose of patching is to allow you to deliver bug fixes and performance optimization to released modules and deliver them to scientists that are already using a released module. In order to understand releasing and patching in Kepler, you need to understand how a few concepts work in Kepler:

Release

Is a snapshot of a particular branch of your module at a particular point of time. There are three types of releases, major, minor, and patch. In technical terms, major and minor releases are identical, in that neither is guaranteed to be compatible or even similar to previous releases. However, your decision to make a major versus a minor release informally communicates to the end user the magnitude of the differences between snapshots.

Patch

1. Very minor feature enhancements that do not affect the substantive execution of workflows in anyway. An example would be a feature that allow scientists to monitor but not change a particular workflow value during execution. Such changes, especially if they involve modifications of the GUI in some way, should not be disruptive to the user and should involve neither substractions nor additions to either the public or protected API.
   
2. Performance enhancements that do not involve any substantive change to workflow execution and involve neither subtractions nor additions to either the public or protected API
   
3. Bug fixes which do not impact either the public or protected API.
   

Version

 A version is a unique number that uniquely identifies a particular branch or release. A branch version number has two parts, major and minor (<major>.<minor> e.g. 0.1, 1.2, 5.2, etc.) while a release version number has three parts, corresponding to the three types of releases, major, minor, and patch (<major>.<minor>.<patch> e.g. 0.1.2, 1.4.0, 7.3.2, etc.)

You need to choose a major and minor version number when you patch. For example, many people will start with 1.0 for there first branch. Subsequent patches (with the "ant patch" command) will increment the patch number. Thus, the two commands that culminate in releases with unique version numbers are "ant release" and "ant patch." For a given branch, "ant release" can only be used once, whereas "ant patch" may be used any number of times.

 Finally, note that it is possible for patch to be specified as "^" instead of a number. This means that the system should try to use the latest available patch. For example, imagine that a version was specified as 1.2.^ and 1.2.0, 1.2.1, 1.2.2, 1.2.3, and 1.2.4 were all released. The system will resolve 1.2.^ to 1.2.4. In this way, it is possible to build suites that specify that the latest patch should be used.

Basic Steps for Releasing

These instructions will be illustrated with the following example. Imagine that you are releasing a suite called my-suite and a module called my-module. That suite contains a reference to my-module and kepler-2.0.^, which is already released.

The modules.txt for my-suite looks like the following:

my-module
*kepler-2.0.^

Note: Suites do not have to reference themselves. Therefore, the my-suite module is included, even though it is not explicitly referenced. Also, imagine that kepler-2.0.0, kepler-2.0.1, and kepler-2.0.2 are available. As mentioned above then, the reference to kepler-2.0.^ should resolve itself to kepler-2.0.2.

Overview

(1) Create a new branch for each modules you want to release.
(2) Checkout all of the branches you just created.
(3) Update the modules.txt for each branch, and check in your changes.
(4) Compile and jar the code for each branch.
(5) Release each branch.

Create a new branch for each modules you want to release.

It need not be said: you should engage in testing before releasing. Make sure that all of your work on your local machine is checked in, since branching does not interact with your local copy, but instead with what is checked into the server.

Going back to our example, you need to branch both my-suite and my-module. The reason is that you may not release off the trunk of a module, but only off of a branch. This enables patching later, if it is necessary.

Before branching, you need to decide whether this release will be major or minor. There is no technical difference, but generally you should increment the minor number for a minor release and the major number for a major release. This will communicate to your users how significant you consider this release. Since this is our first release and we want it to be 1.0, we will use the branch command as follows.

You would enter the following commands:

ant branch -Dmodule=my-suite -Dversion=1.0
ant branch -Dmodule=my-module -Dversion=1.0

Checkout all of the branches you just created.

The branches you created are now on the SVN repository for Kepler. However, unlike branching, releasing itself occurs from your local copy. So, you need to retrieve the modules you just released with the following commands:

ant get -Dmodule=my-suite-1.0
ant get -Dmodule=my-module-1.0

Update the modules.txt for each branch, and check in your changes.

There is a problem. If you try to change-to my suite (e.g. ant change-to -Dsuite=my-suite), it will retrieve the wrong version of my-module. Instead of referencing the branch my-module-1.0, it references the trunk my-module. You want branches to reference other branches, rather than the trunk, so that the branch remains stable except for intentional patches.

In our example, my-suite-1.0/module-info/modules.txt has the following contents:

my-module
*kepler-2.0.^

Change this to:

my-module-1.0
*kepler-2.0.^

It is vital that you check in this change this right away, because you are going to need to change modules.txt again in your local copy for releasing purposes. Enter the following command:

svn ci ../my-suite-1.0 -m "Changing modules.txt in my-suite-1.0."

Compile and jar the code for each branch.

Now that you have changed the modules.txt for the suite, you need to compile and jar all the modules that you want to release. For efficiency purposes and because you cannot expect users to do any compilation on their machines, released modules are always executed from jars. To do that in our example, you would enter the following commands:

ant change-to -Dsuite=my-suite-1.0
ant jar

Release each branch.

Before releasing, you need to once again modify the modules.txt for each suite that you intend to release. However, it is important that you keep all such modifications in your local copy only and do not check them into the branch (unless you happen to want the branch to refer to released versions of the other modules referenced instead of the branch).

In our example change the modules.txt in my-suite-1.0/module-info/modules.txt from:

my-module-1.0
*kepler-2.0.^

to:

my-module-1.0.^
*kepler-2.0.^

This will ensure that the latest patch is always retrieved. However, if you wanted to it so that the latest patch wasn't retrieved, you could use my-module-1.0.0 instead of my-module-1.0.^.

Next, you need to release both my-module and my-suite. Use the following commands:

ant release -Dmodule=my-module-1.0
ant release -Dsuite=my-suite-1.0

These will be released as my-module-1.0.0 and my-suite-1.0.0. Note that you could also release my-suite using "ant release -Dmodule=my-suite-1.0". This would prevent my-suite-1.0 from being available as a suite in the Module Manager GUI, but it would instead be available as a module. Just because something is a suite in the build system does not mean it is a suite for release purposes. If you want it to be released as a suite that is visible in the Module Manager GUI, it is important that you use "ant release -Dsuite=<branch.name>" and not "ant release -Dmodule=<branch.name>".

You are nearly set. The last thing you should do is revert the temporary changes you made to modules.txt for the purposes of releasing:

svn revert ../my-suite-1.0/module-info/modules.txt

After this, modules.txt for my-suite-1.0 should look like this again:

my-module-1.0
*kepler-2.0.^

Patching

The steps for patching are identical to the steps for releasing, except that instead of using the "ant release" command you use the "ant patch" patch. So, say that you have released my-module-2.2.0 and you want to make a patch called my-module-2.2.1. Essentially, you would put all of your changes in the my-module-2.2 release branch. Then you would simply follow all of the steps above for releasing, except substituting "ant patch" for any references to "ant release" in the instructions.

Note: Do to an issue involving the transition from Java 1.5 to Java 1.6, at this time, patches to either kepler-2.0 or kepler-2.1 are not allowed.