OLFSReleaseGuide

From OPeNDAP Documentation

<< back to HowTo Guides

1 Overview

This document describes how to make releases of the OLFS.

About version numbers:

  • We use Hyrax <major>.<minor> version numbers for release branches.
  • We use <major>.<minor>.<revision> version numbers for the olfs code version.

New versions of a release (only the <revision> field in the version number is changed) should contain:

  • Bug fixes.
  • Updated tests.
  • Changes to production rules.

These changes should be made on the trunk and the merged to the release branch.

Since major development is only happening on development branches, very little on the trunk should change until a development branch is merged into the trunk. If new features are added or the code API changes there should be a new release made, which means make a new release branch.

This page is based on the branching and merging guidelines found here.

2 Make sure the code is ready to release

Make sure that all of the developers working on the code have checked in their working copies of the trunk, and that all development branches whose functionality/features/codeBase are to included in the release have been merged to the trunk and committed.

2.1 Check out the OLFS code from the subversion trunk

In a new directory get a fresh copy of the trunk:

git clone https://github.com/opendap/olfs

2.2 Build the OLFS

In the checked out OLFS directory run the command:

% ant server

2.3 Run the tests

Updated Jan 26th 2016

The OLFS utilizes an autotools/automake/autotest test system. In order to to run the tests you must build and install the BES first. Then build and install the OLFS into a Tomcat instance and start that instance.

NB - Do NOT specify version numbers at this stage as the test baselines are set up for the default version number of Not.A.Release. Building with a non-default version number will cause at least 12 tests to fail.

Once you have the OLFS built, installed, and running, return to the olfs top level directory and run:

autoreconf -vif
./configure
make check

This will run the tests in a traditional autotest test harness.

3 Determine Version Numbers

You will need to know the OLFS version and the Hyrax version of the release to build the distribution and to update the various release related files.

3.1 OLFS Version Number

  1. Look in the NEWS and README files to determine the previous version number.
  2. Determine new version number by looking at the changes to the code (start by reviewing the ChangeLog file)
    • Versioning rules: What the MAJOR.MINOR.REVISION string means:
      • No interfaces changed, only implementations (good): ==> Increment REVISION.
      • Interfaces added, none removed (good): ==> Increment MINOR, set REVISION to 0.
      • Interfaces removed or changed (BAD, breaks upward compatibility): ==> Increment MAJOR, set MINOR and REVISION to 0.
  3. Remember the new version number so that it can be used to:
    • Update the release related files
    • Build the versioned software distribution bundles.

3.2 Hyrax Version

Need a set of criteria or a link to them here.

4 Edit the release related files

ChangeLog
Use the script gitlog-to-changelog (which can be found with Google) to update the ChangeLog file by running it using the --since="<date>" option with a date one day later in time than the newest entry in the current ChangeLog. Then, to write the NEWS file, just read over the new ChangeLog entries and summarize.
README.md
Update version number.
Review content to make sure it's current.
NEWS
Add new version number and,
Summarize the new additions to the change log. There may be many checkins associated with new feature development. You can summarize those as "Added 'X' feature."
install.html
Update version number.
Review content to make sure it's current.

5 Check in changes

In the local copy of the OLFS master branch in which you updated the ChangeLog and other files:

git commit -a -m "olfs: Updating olfs version and release files to version 1.2.3"

Once this is done, use github to tag the code you just committed both with its version and the version of hyrax to which it belongs:

5.1 Tag the release

git tag -a olfs-<numbers> -m "OLFS <number>"
git push origin olfs-<numbers>

5.2 If this is part of Hyrax, also tag this point in the master branch with the Hyrax release number

git tag -a hyrax-<numbers> -m "Hyrax <number>"
git push origin hyrax-<numbers>
Note
Instead of tagging all of the modules, use the saved commit hashes that git tracks for submodules. This cuts down on the bookkeeping for releases and removes one source of error; recording the wrong version for one of the 17 or so modules. thus, there is no need to tag the code in the modules.


6 Build the versioned distribution bundles

In the local copy of the software:

ant -DOLFS_VERSION=1.2.3 -DHYRAX_VERSION=4.5.0 DISTRO

This will create the three compressed tar files for the release in the $olfs/build/dist directory.

olfs-1.2.3-doc.tgz
Contains the javadoc documentation for the release
olfs-1.2.3-src.tgz
Contains the source files for the release
olfs-1.2.3-webapp.tgz
Contains the instructions and .war file that will be used in the tomcat webapps directory.

Use GPG to detach sign each of these three files and you're ready to upload them to the website for distribution.

The OLFS has historically been published here: http://www.opendap.org/pub/olfs/