From IcedTea

Jump to: navigation, search

Thermostat Home


1 Thermostat versioning, working with release branches, and performing releases

1.1 Versioning

Thermostat roughly follows a Semantic Versioning schema, with some minor differences.

  • We normally refer to "micro" version as opposed to "patch" version.
  • In order to work around conflict between OSGi vs Maven versioning, we use an odd/even versioning scheme. Odd micro versions will always be unstable/devel snapshots, even micro versions are reserved for actual releases. For example, 1.3.5-SNAPSHOT will be released as 1.3.6.
  • We also use odd/even at the minor version level, to avoid ambiguity between trunk and any release branches. Trunk is always bumped ahead to one minor version above the highest release branch.
  • To further avoid the potential for ambiguity of whether a build comes from a released version or a devel snapshot, during development the qualifier "SNAPSHOT" is always present, but it is removed for release.
  • Until we reach 1.0, we will only support a single release at any given time. As a side effect, there will likely only ever be a single micro release (.0) for each minor version until then.

1.2 List of Thermostat branches and tips for working with branches

Thermostat uses server-side branches (as opposed to in-repo branching) for each minor version, and tags within these branches for each micro version that is released.

1.2.1 Active branches

TRUNK: /hg/thermostat hgweb

This is where active development takes place. Any committer can approve another committer's patches. Approval is normally received over the mailing list.

Stable: /hg/release/thermostat-1.6 hgweb

Branch for 1.6.X releases. Backwards compatible changes are accepted for this branch. Such changes should be first considered for TRUNK, and then backported to this branch.

STABLE: /hg/release/thermostat-1.4 hgweb

Branch for 1.4.X releases. Only bugfixes are accepted for this branch. Bugs should be first fixed in TRUNK and allowed to soak before backporting to this branch. A backport bug clone separate from the original bug report should be created for any backports to this branch. Such bugs should have the *target* field set to the next release due from this branch. Please ensure branch maintainer is in the loop for any push to this branch.

1.2.2 Dead branches

0.4: /hg/release/thermostat-0.4 hgweb From this branch, we released 0.4.0. It is no longer supported or maintained.

0.5: /hg/release/thermostat-0.5 hgweb From this branch, we released 0.5.0. It is no longer supported or maintained.

0.6: /hg/release/thermostat-0.6 hgweb From this branch, we released 0.6.0. It is no longer supported or maintained.

0.7: /hg/release/thermostat-0.7 hgweb From this branch, we released 0.7.0. It is no longer supported or maintained.

0.9: /hg/release/thermostat-0.9 hgweb From this branch, we released 0.9.0 and an emergency bugfix release 0.9.1. It is no longer supported or maintained.

0.11: /hg/release/thermostat-0.11 hgweb From this branch, we released 0.11.0. It is no longer supported or maintained.

0.13: /hg/release/thermostat-0.13 hgweb From this branch, we released 0.13.0. It is no longer supported or maintained.

0.15: /hg/release/thermostat-0.15 hgweb From this branch, we released 0.15.0. It is no longer supported or maintained.

1.0: /hg/release/thermostat-1.0 hgweb From this branch, we released 1.0.x. It is no longer supported or maintained.

1.2: /hg/release/thermostat-1.2 hgweb From this branch, we released 1.2.x. It is no longer supported or maintained. Security fixes can be backported to this branch.

1.2.3 Making a new release branch

The assumption is that the eventual first release from this branch will be x.y.z, so change these values as appropriate for any commands below.

First, create the branch on the IcedTea servers.

ssh hg-remote-clone /hg/thermostat /hg/release/thermostat-x.y

Now, ensure that you have a clone of the trunk and the release branch. In the trunk:

Tag the parent of the release branch:

hg tag -r <revision branched from> x.y-branchpoint

Use the included update-version utility to bump the snapshot version for trunk:

 ./distribution/tools/update-version -t  x.<y-1>.0 x.<y+1>.0

Make sure to review the output of this utility before committing and pushing, as it performs some checks to ensure that version metadata is updated everywhere necessary. See --help for this utility for more information. You may even want to do a test build as well.

 hg commit
 hg push

The net change in minor version in trunk for this bump is, intentionally, 2. Trunk should always be an odd minor version, one version higher than the most recent release branch. We reserve even minor versions for release branches. Because we don't perform releases from the trunk, the micro version here should always be 0. In release branch clone:

Tag the branch:

 hg tag x.y-branch
 hg push

Now edit the active branch information higher up on this page to reflect the new branch. Don't bump the release branch version until you are ready to perform the release.

1.3 Performing Thermostat releases

Below, replace x/y/z as appropriate.

In release branch clone:

For versions up to and including 1.2 only: First, make the default build a "release type" build (see builds FAQ page) via the following patch:

diff --git a/distribution/pom.xml b/distribution/pom.xml
--- a/distribution/pom.xml
+++ b/distribution/pom.xml
@@ -264,7 +264,7 @@
-          <value>!release</value>
+          <value>dev</value>
@@ -302,10 +302,7 @@
-        <property>
-          <name>environment.type</name>
-          <value>release</value>
-        </property>
+        <activeByDefault>true</activeByDefault>
diff --git a/pom.xml b/pom.xml
--- a/pom.xml
+++ b/pom.xml
@@ -76,7 +76,7 @@
-          <value>!release</value>
+          <value>dev</value>

After this, be sure that

$ mvn help:active-profiles

Produces the same output (pending timestamps) than the following on an unpatched HEAD version

$ mvn -Denvironment.type=release help:active-profiles

Next, remove the SNAPSHOT qualifier. If this is the x.y.0 release:

 ./distribution/tools/update-version -r x.<y-1>.0 x.y.0

Or, for further updates to the release branch:

 ./distribution/tools/update-version -r x.y.<z-1> x.y.z

Again, check the output for warnings and review any files listed manually. The script will suggest that you do a full build at this stage. Do this, or risk publishing a broken release!

Before you commit, edit distribution/config/ and set the log level to WARNING. If everything has gone well up until this point, commit and tag and push to remote.

 hg commit
 hg tag -r <revision you just committed> x.y.z
 hg push

Create and upload the release tarball and md5sum (you may need to be someone with special shell privileges on the server to do this):

 hg archive thermostat-x.y.z.tar.gz -r <same revision as above>
 md5sum thermostat-x.y.z.tar.gz > thermostat-x.y.z.tar.gz.md5
 scp thermostat-x.y.z* <your-user-name>

At this point, you can write up a release announcement and send it out to the mailing list. But, in case there will be further work done on the release branch, you should now return distribution/config/ to the CONFIG setting, and bump the micro version and restore the SNAPSHOT qualifier:

 ./distribution/tools/update-version -d x.y.z x.y.<z+1>

Again, ensure that you are satisified with the changes before committing and pushing.

 hg commit
 hg push

You're almost done! Now you need to update the Thermostat project page with the new release information. The page is maintained in a separate repository, which includes a simple makefile to help deploying to the web server over rsync. If you haven't yet cloned it:

 hg clone ssh://
 cd thermostat-website

Edit index.html, adding an entry in the Downloads table for the new release tarball. Commit and push, then use make to easily deploy.

 hg commit
 hg push
 scp index.html <your-user-name>

Note that not all IcedTea hackers have a shell account which permits this operation. If you are unable to perform the deployment step, ask in the #thermostat channel on Freenode for someone to help.

Personal tools