How to Make a Release
This is an updated set of notes regarding a software release. It is tailored to a release of Hyrax, but the same process can be used for any of our code.
- Look for any tickets that have been bound to the label 'fix release x.y.z' and make sure those are completed. Use the Kanban board.
- When we are ready to release, follow the process outlined in the sections below.
- Once done, close the board
- 1 When we decide to release software
- 2 Release Prerequisites
- 3 Steps For A Major Release (ex: 1.16.x -> 1.17.0)
- 4 Steps For A Minor Release (ex: 1.16.5 -> 1.16.6)
- 4.1 Perform the Jira Release Process
- 4.2 hyrax-dependencies: Source Release For hyrax-dependencies
- 4.3 libdap: Source Release for libdap
- 4.4 BES: Source Release for BES
- 4.5 OLFS: Source and Binary release for OLFS
- 4.6 Sign And Publish The C++ Binary Distributions
- 4.7 Build And Publish Docker Images For The Release
- 4.8 Install the new server on test.opendap.org
- 5 Update The Hyrax Release Web Page On The OPeNDAP Website
- 6 Send out a notice.
- 7 Time to complete by release
1 When we decide to release software
Use the developers at opendap.org list to send out notices to all the developers about pending releases.
1.1 Planned release
If this is a planned release, send out a notice at least two weeks in advance to anyone who likely has made changes to the software. More lead time is, of course, better. This will allow developers time to get their code and documentation changes into github and onto the master branch in time for the release.
1.2 Emergency releases
If this is an 'emergency' release, then send out a notice to developers as soon as the decision to release is made, since this will give a chance for other developers to lets us know if there are new changes in the master branch that are ready for release. if we don't get an email from those developers of a particular component, then we should assume that the code might not be 100% ready for release and we should use the version tagged with/for the last release if possible.
Maybe run Coverity - depends on the scope of the changes.
2 Release Prerequisites
Only start this process when hyrax-dependencies, libdap, bes and OLFS master branches all building and passing their tests.
3 Steps For A Major Release (ex: 1.16.x -> 1.17.0)
- Security Review for libdap, BES and OLFS Now Handled By TravisCI
- Write a new X.Y web page. See the web site admin notes for info about this. It has important information about the menu links. Base this on the previous release page's structure/content.
- Follow the remaining steps for a minor release (below).
4 Steps For A Minor Release (ex: 1.16.5 -> 1.16.6)
- Committing and pushing the various changes made for the source releases will trigger a binary build and those binaries will have the version numbers made in the source distributions update.
- Perform these steps in the order stated as downstream activities rely on items created in earlier steps, such as the creation of the DOIs for libdap and BES are required when updating the OLFS README.md,
4.1 Perform the Jira Release Process
4.2 hyrax-dependencies: Source Release For hyrax-dependencies
4.3 libdap: Source Release for libdap
4.4 BES: Source Release for BES
4.5 OLFS: Source and Binary release for OLFS
4.6 Sign And Publish The C++ Binary Distributions
Note: This was already done for the java OLFS in the previous steps.
4.6.1 Retrieve the binary RPM packages built using the CI/CD process
- Pull the binary packages from our opendap.travis.build S3 bucket. Log into the OPeNDAP AWS account and goto: https://s3.console.aws.amazon.com/s3/buckets/opendap.travis.build?region=us-east-1&tab=objects
- Locate and download the most recent builds of the libdap4 to your system. This is easily done by filtering on the string "libdap" and then sorting by date so the most recent builds are at the top.. Be sure to get the library, developer, and debug info rpms for each architecture. For example if the version is <numbers> and the architecture is CentOS-7 get:
- Locate and download the most recent builds of the BES to your system. This is easily done by filtering on the string "bes" and then sorting by date so the most recent builds are at the top. Be sure to get the library, developer, and debug info rpms for each architecture. For example if the version is <numbers> and the architecture is CentOS-7 get:
4.6.2 Sign the RPM packages
In the directory containing only the RPM packages for the release run the following command:
for i in *.rpm;do gpg --detach-sign --local-user email@example.com $i; done
4.6.3 Publish the RPM packages and their signatures
- Use sftp to log into www.opendap.org
- cd httpdocs/pub/binary/hyrax.XX.YY/<os-name>
- (where XX.YY is the major release number, ex: 1.16 and <os-name> is something like centos-7 for CentOS-7 RPMs): https://www.opendap.org/pub/binary/hyrax-1.16/centos-7.x/
- put *.rpm*
4.8 Install the new server on test.opendap.org
5 Update The Hyrax Release Web Page On The OPeNDAP Website
Currently we have a single page for each major release. Minor release information is added to the major release page to which the minor release is associated. For example if you are making minor release Hyrax-1.16.5 then you would add the release information to the Hyrax-1.16 page.
5.1 Creating A Major Release Page
- If this is a major release copy the previous major release X.Y page to X.(Y+1).
- Clear out the contents of the page while maintaining the structure:
- Release Information
- New Features (Remove content.)
- Bug Fixes (Remove content.)
- Hyrax Software Downloads (Keep contents but update as described in the Minor Release section below.)
- Required External Dependencies (Ibid)
- Binary Packages (Ibid)
- Installation Summary (Ibid)
- Source Code (Ibid)
- GitHub (Ibid)
- Snapshots (Ibid)
- Hyrax Server Documentation (Ibid)
- Release Information
- Follow the instructions for updating the web page for a Minor Release below.
5.2 Updating The Release Page For A Minor Release
5.2.1 Update the New Features section
- Under "New Features" create a new sub-section (Heading 2) titled "Added in Hyrax-xx.yy.zz" section for the new release. If this is a major release then zz==0, example: Hyrax-1.16.0
- Create an Anchor at the beginning of this new heading titled "hyrax-.xx.yy.zz-features".
- In the abbreviated table of contents at the top of the page add a new link in the bullet list under "New Features" titled "hyrax-xx.yy.zz" and point the link to your new anchor "#hyrax-xx.yy.zz-features"
- Take the entires that you made to the change log and enter them into this new section, format them for readability and navigability. (See previous releases for examples.)
- Update the links on the web page made/copies/edited above. Test each link - source and binary. Once all of those work...
- Publish the release page. Check the links - there are links in two menus that have to be set manually.
6 Send out a notice.
7 Time to complete by release
Update and of the release checklists and the 'Time to complete...' information below.
- Hyrax 1.12.2: The total time was planned as 3w 1d 5h and turned out as 1w 2d 2h 10m.
- Hyrax 1.15.1: 3d calendar time
- Hyrax 1.16.2: 3d effort