Release Process

Some notes on how Roller releases are orchestrated.

The Release Cycle

Roller releases are made on an as needed basis. Here's an overview of the release cycle.

When a Roller PMC member would like to make a release at some point in the future, he/she simply proposes that release to the Roller private mailing list.

After some of the planned features are added, a committer may propose a milestone build. Milestone builds are not official releases, each is just a snapshot, so formal vote is not required, only lazy consensus. They may be tagged in SVN and are made available via informal mechanisms, e.g. a committers people.apache.org space. They are meant for testing only and not intended for production use, so there will be no migration scripts to help folks migrate data from milestone M1 to M2, etc.

Once a committer feels that the release is completely ready, he/she proposes to start making release candidates. A release candidate is a complete release, signed and ready to be shipped. Like milestone releases, release candidates are not official releases. They are meant for testing only and not intended for production use. After some feedback and testing has occurred and a release candidate appears to be good for final release, a vote is called. Once there are three +1 votes from PMC members the release can be made.

That's the overview, now let's talk details.

Contributing to a release

If you want to add a feature to a release, you should create a JIRA issue describing the feature, assign it to yourself, and set the "fix-for" field for the release you want. (see the roadmap view in JIRA). For all but the smallest improvements and bug fixes, you should also write a proposal and get it reviewed by the community on the development mailing list. If you are working on a feature marked as IN-PROGRESS in JIRA, then when you are done you should mark it as RESOLVED. Any work that is completed should be properly documented (user guide and/or install guide), change lists should be updated, and if needed database scripts are updated and tested.

Release Numbers and Versions

Roller follows the typical Major.Minor.Patch version numbering convention.

Major releases

A major release is noted by a change in the major release number (i.e. 1.x to 2.x). major releases are like any other Roller release except that they are expected to include potential database schema changes and for that reason the upgrade procedure may be longer and more involved. major releases are also expected to contain larger sets of changes and more complex feature additions which were too large to complete in a minor release.

Minor releases

A minor release is noted by a change in the minor release number (i.e. 1.2 to 1.3). minor releases typically contain smaller changes to the code base and can be easily upgraded. Roller users should feel very comfortable about upgrading their Roller installation with a new minor release.

Patch releases (emergency bug fixes)

We expect that each release of roller will simply be considered a minor release, however should something unfortunate happen and we must do an emergency bug fix for a given release then we may mark that release with an incremental patch version number (i.e. 1.3.1). this is not expected to happen often.

Where Work Gets Done

This section tells you where the right place is for your code and in general how the Roller repository is structured.

Roller Trunk

The Roller trunk is the main development repository and will try to always represent the version of the code base currently being developed for the next release. Each new release will be made from the trunk and distributed as appropriate. It is expected that any code commited to the trunk will be in full working order _in time for the next scheduled release_

Roller Release branch

At some point while we are making release candidates for a Roller release, we may decide to create a branch for the release. We do this in cases where it is very important that post-release development continue in the trunk.

Custom branches

A custom branch can be created whenever a feature is in development that is not on a certain schedule. this allows the custom branch to worked at whatever pace is desired and when the code is ready it can be applied to whatever branch is most appropriate.

Tags

All tags in the subversion repository are meant to be read-only archives of versions of Roller that went final. If you are ever looking for the code to a specific version of Roller you should look here. In roller svn this is at tags/*.

Step-by-step How to Create a Release

NOTE: these instructions are for the Roller 5.0 branch and with Roller 5.1 (yet to be released) these instructions will change.

1. Obtain and update the source code.

Check out the Apache Roller source code from the appropriate branch.  Within the pom files, update the Roller version number to what you will be releasing (for example, 5.0.4-SNAPSHOT to 5.0.4).  Update the version within the three sign*.sh files to that version as well.

2. Create release for Tomcat

The commands below will create the Roller for Tomcat release bundle in ZIP and Gzipped TAR formats and the ASCii signature files:

   ./build-tomcat-release.sh
   ./sign-tomcat-release.sh

Once done, move the six files (tar/gz/source & .asc for them) outside of weblogger-assembly/target folder (otherwise, those files will be lost in the Java EE build in the next step).

3. Create release for Java EE

The commands below will create the Roller for Java EE release bundle in ZIP and Gzipped TAR formats and the ASCii signature files:

   ./build-javaee-release.sh
   ./sign-javaee-release.sh

After that, four files (tar/gz & .asc for them) will be in the weblogger-assembly/target directory.

3. Create release for Java EE

The commands below will create the Roller for Java EE release bundle in ZIP and Gzipped TAR formats and the ASCii signature files:

   ./build-javaee-release.sh
   ./sign-javaee-release.sh

After that, four files (tar/gz & .asc for them) will be in the weblogger-assembly/target directory. 

If you haven't already, you will also need to upload your public key to the KEYS file in the Roller distribution folder.  This has to be done only once for Roller no matter how many releases you make.  First use "gpg --list-keys" to determine the 8 character key ID for your key, and then make an ASCII armored key for it and add it to the MIT public key server.  For the SVN KEYS file, do an empty checkout of the folder (to avoid downloading the several large artifacts in this folder's hierarchy) and then an individual file svn update to get just the KEYS file, add your public key to it using the instructions at the top of the file, and then commit the KEYS file back:

svn co https://dist.apache.org/repos/dist/release/roller --depth=empty
cd roller
svn update KEYS
(add public key to KEYS)
svn commit KEYS -m "Added my key to KEYS file."

For the Roller distribution KEYS file, do an ssh to <your apache user id>@people.apache.org, navigate to the /dist/roller folder, and use vi or another command line tool to add your KEY to that file.  (For vi, go to the end of the file by entering a capital G followed by a small o to enter edit mode, then paste your key in, followed by an Escape key and a :wq to save the file.)

4. Check In Version changes

Do an SVN commit of the changes you did in Step #1.  Then, add a release candidate tag using the svn copy command, for example:

svn copy https://svn.apache.org/repos/asf/roller/branches/roller_5.0  https://svn.apache.org/repos/asf/roller/tags/roller_5.0.4-rc1

5. Move artifacts to Roller Dist - Dev folder and Vote on release

We use svnpubsub for our distribution releases (docs).  We upload the artifacts to the dist/dev/roller folder (using svn add) when we hold the vote.  After the vote is approved use an svn move to move the artifacts to the dist/release/roller folder.  As the dist/dev and dist/release folders have countless artifacts from all the other Apache projects, use the SVN --depth=empty commands below to check out just the Roller folders, as shown in the following SVN commands:

svn co https://dist.apache.org/repos/dist roller-dist --depth=empty
cd roller-dist
svn update dev --depth=empty
svn update dev/roller
svn update release --depth=empty
svn update release/roller

Use svn add & svn commit to place the artifacts in the dev/roller/roller-5/v5.?/src, /docs, and /bin folders, similar to that done for earlier releases.

Call for a release vote on the DEV list and once the release is approved, move to the next step.  If there are any not-yet-publicized security issues that the patch fixes, don't mention them in that public email but do so instead on the separate Roller private (PMC-only) list. 

6. Move release files into place

Do an svn (remote) move of the dist/dev/roller/roller-5/v?.?.? folder to the dist/release/roller/roller-5 directory.  With this change the dev directory should be empty.  From the release/roller folder, do an svn rm of older releases from the same branch and of older, no-longer-supported branches as a result of the new release.  (Older releases are already archived elsewhere by the infrastructure team.) Wait up to 24 hours for mirrors to update.

As these files are huge it is considerably faster to move the files remotely on the SVN server instead of doing a local svn move followed by an SVN commit of those files back to the server, for example:

dist$ mkdir release/roller/roller-5/v5.0.4
dist$ svn commit release/roller/roller-5/v5.0.4 -m "Folder for new 5.0.4 release"
dist$ svn move https://dist.apache.org/repos/dist/dev/roller/roller-5/v5.0.4 https://dist.apache.org/repos/dist/release/roller/roller-5/v5.0.4

7. Update the website to point to the new files

Update the website's download and sidebar links in SVN and publish them.

8. Announce the release, update branch version

Make the announcement on the mailing list and other places, and update the branch to the next snapshot version (e.g., 5.0.4 to 5.0.5-SNAPSHOT).