This document summarises the release procedures for FOLIO projects.

Introduction

There are separate notes about the FOLIO version-numbering scheme.

Maven-based modules

The procedure is outlined here for “Okapi” and is similar for other Maven-based modules.

Ensure POM declarations

For Maven-based projects, the Maven Release Plugin is required. To enable the release plugin, add the following to the parent POM of the project:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-release-plugin</artifactId>
  <version>2.5.3</version>
  <configuration>
    <preparationGoals>clean verify</preparationGoals>
    <tagNameFormat>v@{project.version}</tagNameFormat>
    <pushChanges>false</pushChanges>
    <localCheckout>true</localCheckout>
  </configuration>
</plugin>

FOLIO projects which need to deploy artifacts to the FOLIO Maven repository during the Maven ‘deploy’ phase should have the following specified in the project’s top-level POM:

  <distributionManagement>
    <repository>
      <id>folio-nexus</id>
      <name>FOLIO Release Repository</name>
      <url>https://repository.folio.org/repository/maven-releases/</url>
      <uniqueVersion>false</uniqueVersion>
      <layout>default</layout>
    </repository>
    <snapshotRepository>
      <id>folio-nexus</id>
      <name>FOLIO Snapshot Repository</name>
      <uniqueVersion>true</uniqueVersion>
      <url>https://repository.folio.org/repository/maven-snapshots/</url>
      <layout>default</layout>
    </snapshotRepository>
  </distributionManagement>

  <scm>
    <url>https://github.com/folio-org/PROJECT_NAME</url>
    <connection>scm:git:git://github.com/folio-org/PROJECT_NAME.git</connection>
    <developerConnection>scm:git:git@github.com:folio-org/PROJECT_NAME.git</developerConnection>
    <tag>HEAD</tag>
  </scm>

Replace ‘PROJECT_NAME’ above with the name of the appropriate github repository. Commit all changes to the POM in git.

Ensure that Jira issues are ready

For the issues that are associated with this release, ensure that they reflect reality, have the relevant Fix Version parameter, and are closed.

Make a release branch

If you do not have commit access to the master branch (and even if you do), you can make the release on a branch.

git checkout -b "release X.Y.Z"

Prepare the news document

Edit NEWS.md to add concise descriptions and issue numbers for each major item. Take extra care with spelling and readability.

git commit -m "Update NEWS" NEWS.md

Update any scripts and descriptors for release version

Update version numbers in places that maven will not do automatically, to the version you are about to release. That could be ModuleDescriptors, LaunchDescriptors, or scripts you use for testing and development.

Often it is not necessary to have any such. You should be using the autogenerated descriptors. Note that scripts can enable the module without mentioning any version numbers.

git commit -a -m "Towards version X.Y.Z"

Prepare and perform the source release

mvn -DautoVersionSubmodules=true release:clean release:prepare

This command will prompt you for input including the release tag/version, the next post-release SNAPSHOT version, as well as ask you to resolve any SNAPSHOT dependencies if you have any. Do NOT create releases with SNAPSHOT dependencies! Selecting the defaults are typically fine. Your release tag must be prefixed with ‘v’ (the default) and you can always change the next SNAPSHOT version later if necessary.

Assuming there are no build errors, you are ready to push your changes to GitHub.

git push
git push --tags

Update any scripts and descriptors for next development release

Update version numbers in the same places you did earlier, but now for the next development version

git commit -a -m "Towards version X.Y.Q-SNAPSHOT"
git push

Build and release artifacts

An ‘artifact’ in this context could either be a Maven artifact released to the FOLIO Maven repository, a docker image released to Docker Hub, a Linux distribution package or some combination of artifacts depending on the project. To release the artifacts relevant to your project, log into the FOLIO Jenkins system. Navigate to the Release Jobs folder and select your module’s Jenkins job name with the ‘-release’ suffix. For example, ‘okapi-release’. Select ‘Build with Parameters’ and select the release tag you want to release. This will build the release artifacts and deploy them to the proper repositories.

Merge the release branch into master

Go to GitHub and make a pull request for the release branch you just pushed. Wait for all the tests to pass and merge the pull request.

Add release notes to GitHub

Go to the “Releases” area (e.g. Okapi). Select Draft a new release then choose the tag of the new release and add the NEWS portion – only the part of NEWS since previous release.

Prepare Jira for next release

Use the “Admin” interface to “Manage Versions”. Mark the current version as released, and add the next version(s).

Announce

Send a note to #general on Slack if relevant.

Improve this doc

If you found some parts of this guide to be out of date, or hard to understand, now is a good time to fix that. Check out git@github.com:folio-org/folio-org.github.io.git and edit doc/release-procedures.md.

  • OKAPI-287 – Document release procedure
  • OKAPI-265 – Versions in Jira / fix-versions in particular
  • FOLIO-551 – FOLIO release artifacts via Jenkins
  • FOLIO-317 – Identify and implement FOLIO software release process
  • OKAPI-293 – Maven build fails when building from release distributions

Gradle-based modules

The procedure for Gradle-based modules (such as mod-inventory or mod-circulation) is very similar to maven-based modules.

Follow all of the steps for a maven-based module, except ensure POM declarations and replacing Prepare and perform the source release with the steps outlined below.

Change the release version

Using the example of releasing version 4.4.0 of the mod-inventory module for context, the top of the gradle build configuration will look something similar to:

apply plugin: 'groovy'
apply plugin: 'application'

mainClassName = "org.folio.inventory.Launcher"
version = "4.3.1-SNAPSHOT"

Change the version to “4.4.0” and commit the change using a message similar to “Release v4.4.0”.

Create tag representing the release, using a command similar to:

git tag -a v4.4.0

Describing the changes in this release (similar to those put in the news) in the annotation of the tag.

Update to unreleased version

Change the version again to an unreleased snapshot version. In this example it could be “4.4.1-SNAPSHOT” which is the next possible version (or “4.5.0-SNAPSHOT” if the next changes are going to provide new functionality) and commit the change using a message similar to “Increment version number to unreleased version (4.4.1)”.

Trigger the release

Push the changes using commands similar to:

git push origin master
git push origin v4.4.0

Trigger the appropriate release job in Jenkins to publish the release artefacts, choosing the appropriate tag. In this example the release job is mod-inventory-release and the parameter would be the 4.4.0 tag.

Stripes-based modules

All Stripes modules (i.e. stripes-* and ui-*) follow the Stripes release procedure.

  • STRIPES-309 – Align git-repos, NPM-packages and Jira projects for Stripes and UI modules.