Release Process

Introduction

This page documents how to perform a software release. The software release process is largely automated. The high-level process is:

1. Run a shell script to prepare the GitHub repositories for release
2. Build the packages in Jenkins
3. Build the Docker images
4. Build the Toolkit ISOs

Preparing GitHub

Installing the Tools

If you have not done so already, you should install the perfsonar-dev-tools from GitHub that contain a set of utilities for performing release actions. You can clone these tools with the following command:

git clone https://github.com/perfsonar/perfsonar-dev-tools

You may have everything you need at this point and can skip to preparing the release. The downloaded repository does however contain a Vagrant environment for running the scripts. Using the vagrant environment is optional as the tools should run on any system with Git and a shell including Mac and Windows (using the Git bash shell). You can access the Vagrant environment with the following commands:

cd perfsonar-dev-tools
vagrant up
vagrant ssh

Once logged-in to the vagrant environment, you will need to configure git with your access credentials so you can push to the repository( e.g. add you username and password to /home/vagrant/.netrc). All the scripts in the remainder of this document can be found in the shared directory /vagrant/bin.

Beta Releases

Git can be prepared for a beta release by running the following where 4.2.0 is the version and 0.b1.1 is the package release number (note this MUST always start with 0. or the script will complain - don't worry it will be adjusted for Debian):

/vagrant/bin/make-release 4.2.0 0.b1.1

The script will walk through all the repositories and do the following:

1. Checkout a clean copy of the target version branch from git
2. Update the RPM spec files with the correct version and release (and commits this change to git)
3. Verify Debian patches cleanly apply
4. Update the DEB files with the correct version and release (and commits this change to git)
5. Tag the version branch with vVERSION-RELEASE (e.g. v4.2.0-b1.1)

Final Releases

When you are ready for a final release run the following where 4.2.0 is the version:

/vagrant/bin/make-release 4.2.0

The script will walk through all the repositories and do the following:

1. Checkout a clean copy of the target version branch from git
2. Merges the branch forward to next patch (e.g. 4.2.1) and minor (e.g. 4.3.0) release if they exist (creation of these branches occurs in the close-release command discussed later).
3. Update the RPM spec files with the correct version (4.2.0) and release (usually 1) and commits this change to git)
4. Verify Debian patches cleanly apply
5. Update the DEB files with the correct version and release (and commits this change to git)
6. Merges the version branch into master
7. Tags master with vVERSION (e.g. v4.2.0)

After the script has run and you are happy with the result there is one last step: closes the version branch. This adds a file to the version branch that says no changes should be committed. You can optionally enforce this closure by following the directions in the next section. It also creates the necessary branches for next patch and minor release:

/vagrant/bin/close-release 4.2.0 

Not that this step is separate from make-release to give a chance to workout any issues before closing. It should not be run until you are completely certain there will be no more changes (i.e. the release has been announced).

Optional: Enforcing closed-state on Client

See the perfsonar-dev-tools README for information on how to install client-side git hooks on your local machine. These are not strictly required but do prevent accidental commits to a closed branch.

Optional: Enforcing closed-state on GitHub

We may make this a requirement at some point, but to make sure the closed state gets enforced you may perform the following manual steps (if we are able to automate this in the future, it will likely become a hard requirement)

1. Log into GitHub using an administrator account.
2. Go to the repository that is to be closed.
3. Select the Settings tab.
4. Select Branches in the left-side pane.
5. Click Add Rule.
6. Apply the rule to the name of the branch being closed (e.g., 9.1). Note that wildcards are possible, so the number of rules can be kept down by using them. (E.g., if all of the 9.x releases are closed, a single 9* rule would cover all of them.)
7. Select Include administrators.
8. Select Restrict who can push to matching branches. Put only the release administrator, arlake228 on the list.
9. Click Add. Note that the change may take a few minutes to take effect.

Build RPMS and Debian Packages in Jenkins

Currently all packages are built in the perfSONAR Jenkins instance. Talk to the perfSONAR development team for instruction on how to kick-off this process.

Copy RPMs to the Production Yum Repo

This needs to be done on a machine with access to upload to the production RPM repository and with the RPM signing key installed. Talk to the developers for access to these items. Once read the following script will copy all RPMs and SRPMs from staging to the production repository (where 4.2.0 is the version):

/vagrant/bin/depoly-production-rpms.sh 4.2.0

Building Docker Images

For a beta release, the staging tag should automatically build within 24 hours of the change. If you want to trigger it sooner, you can manually start the build in Docker Hub.

For a final release, once you have uploaded all the RPMs, do the following:

1. In the perfsonar-testpoint and perfsonar-tools GitHub repos create a new tag with the version. Docker Hub will automatically build this tag and create a Docker Hub tag so people can easily grab a binary image fixed at this version.
2. In Docker Hub manually trigger a build for latest. This does not auto-start and needs to be done manually through the Docker Hub interface.

Building a Toolkit ISO

See https://github.com/perfsonar/toolkit-building/blob/master/README.md