Creating a bug fix release

Bugfix vs feature branch

We use two types of branches for development work: bugfix and feature. Branches are named for their type as in feature/my-new-work and bugfix/one-last-bug-to-fix.

So, how do they differ?

Bugs are fixed in bugfix branches. Each bug if registered in the feature tracker and gets its own branch for the repair work. These are very focused fixes to known problems. No new features are included. Never fix two identifiable bugs in a single branch. If a fix is not surgical but involves a lot of code then it is best to view it as a feature and do the work on a feature branch and postpone the deployment to the next feature release.

New development work is done in feature branches. To get deployed they must be merged onto develop. Develop holds the content for the next feature release and is always left in a running state. No one cares if your feature branch builds correctly. Everybody cares that develop builds correctly. From develop they are merged, when a release is being formulated, onto master where all released code lives. Every merge from develop to master, in preparation for a release, causes the second number in the version to advance as in 4.4.5 going to 4.5.0. Because many new feature could have been merged onto develop this type of release requires a lot of regression testing.

Creating a bugfix branch

In Intellij...

Most of the branch management tools are in the lower right corner. Here, select the master branch and in its right click menu choose Checkout. Once checked out use the Update Project button at the top of the screen (VCS with a downward pointing arrow). This will make sure your local copy of master is up to date with GitHub. If master is not listed near the top of the list then find origin/master. This will create a local copy.

Once you have a local updated copy of master, click on the bottom right corner branch tool and click on New Branch. It will prompt you for a name. The name should start with bugfix/ and then a name for the fix. The only real requirement is that it be unique and you can remember it. The name will live only as long as you are working on the fix.

The branch tool should now display your new branch name.

Next, fix the problem. This will result in one or more commits. On the last commit, make the commit message start with Fixes #xxx where xxx is the issue number from the GitHub issue tracker. This will cause all kinds of magical things to happen. For instance, when this branch is merged back onto master the issue will be automatically closed (the Fixes #xxx is parsed by GitHub). When this commit message is later copied into the release notes, it will automatically be converted into a link to the issue in the issue tracker. This makes the issue tracker the best place to put all your documentation about a fix. The user can navigate there starting from the release notes.

Now that the bug is fixed and the documentation (including the commit message) is complete you are done. Tell bill the bugfix branch name and he will include it in the next bugfix release. The release notes will be made up of the commit messages that include Fixed #xxx in their title. Do not hesitate to make this wordy if it helps your users. When your bugfix branch is merged onto master (by bill) this branch will be deleted. This means that the branch name will go away. The commits of the branch and the content will remain. It is only the name that disappears.

When the bugfix release is being built there are two moves made. First the bugfix branch is merged back onto master so that the fix is part of the release. Then all the commits on the bugfix branch are cherry picked (copied) onto master. This is to propagate the fix to later release. Once both of these copies are complete bill will delete the bugfix branch.

Some details

The scripts to manage releases are in the top directory of the repository. Several of these scripts only work on Unix machines (Mac and Linux).

Key scripts are:

update-version.sh - Use as

bash update-version.sh new-version

where new-version is the version you want to set. Examples are 4.3.1 or 4.3.1-SNAPSHOT

build-release.sh - Use as

bash build-release.sh

Before running this do:

mvn clean install

This script will take the clean build, build the javadocs and home page resulting in the file

xdstools2/target/xdstools4.war

This file must be renamed for the version (something like xdstools4-4.1.3.war) so that it is ready for upload to GitHub.