Module Releases

Owned by Oleksandr Yatsenko
Last updated: Jul 31, 2020

The purpose of this page is describing module release practical procedures. Mainly these steps are based on general "Release Procedure" but contains some of refinements found in the process of recent release procedures. 

This page could be updated after every new Release if it's needed to provide practically proven steps of the procees. That allows to avoid waste of time to understand some terms and steps of these processes.

All release processes as a rule consist of common steps, but can have some differences which can lead to possible issues in both - the process itself and final result.

Recently there were several kind of releases been completted, therefore both of them will be described here. 

1. General Release of Feature Release *.

This kind of Release performed to rollout some scope of planned changes, as usual it carried out on regular basis, at the end of group of sprint's cycles etc.

Let assume that we need to prepare a new release with the number: 2.2.1 and the tag: v2.2.1. In term of mentioned above general instruction, perepared release number is: X.Y.1 (mentioned instruction was written in context of version: X.Y.0).

  • Create a new release branch out of master - main development branch:

1) git checkout master (swith to the main development branch);

2) git pull (retrives latest changes to branch);

3) git checkout -b tmp-release-2.2.1 (creates a new release branch);

4) vi NEWS.md (edits release notes file and add description of release's features. Example below);

This release includes minor bug fixes for edge-oai-pmh module (Q2/2020).
https://folio-org.atlassian.net/browse/EDGOAIPMH-49

5) git commit -m "Update NEWS" NEWS.md (commits changes in release notes files);

6) mvn -DautoVersionSubmodules=true release:clean release:prepare (runs maven release buld process. Here we need to check and setup release number, tag number and next feature version number)

In this partucilar case we need to specify these versions (proposed default values are based on current version in master development branch - 2.3.0-SNAPSHOT, so they needs to be corrected):

What is the release version for "Edge API - OAI-PMH"? (org.folio:edge-oai-pmh) 2.3.0: : 2.2.1

What is SCM release tag or label for "Edge API - OAI-PMH"? (org.folio:edge-oai-pmh) v2.2.1: : v2.2.1

What is the new development version for "Edge API - OAI-PMH"? (org.folio:edge-oai-pmh) 2.2.2-SNAPSHOT: : 2.3.0-SNAPSHOT

7) git push origin tmp-release-2.2.1 && git push --tags origin tmp-release-2.2.1 (pushing local changes, release notes in this case, with tags to remote stash)

8) Create a new release's description in module repository on GitHub. For example, for mentioned EDGE-OAI-PMH module there is Release v2.2.1 created. To do so:

8.1) go to module's Code page click on the Releases link and pickup Releases tab;

8.2) click on the "Draft a new release" button and fill fields with data:

a) in the fiield "Tag version" specify release's tag number: v2.2.1 and check target branch is set to master;

b) as a release title also specify release's tag number: v2.2.1;

c) in the description field, some kind of release's description can be specified:

This release includes minor bug fixes for edge-oai-pmh module (Q2/2020).
https://folio-org.atlassian.net/browse/EDGOAIPMH-49

8.3) set flag "This is pre-release" and click "Safe draft".

9) Run release job: 

9.1) log in to Jenkins, choose appropriate tag on the "Tags" tab (was created by push operation of the step 7th)

9.2) trigger Build Now.

Please don't forget to run jenkins build on release's tag!!!

10) Merge release's branch into the master. This will allow to  back porting created release's tag number (v2.2.1) into the mainstream development branch, i.e. master.

11) After successfull completion of all the build jobs on Jenkins environment, already prepared release on GutHub (at the step 8th) can be published:

11.1) go to the module's Code page and pickup Releases tab;

11.2) choose prepared, at the step 8th above, "draft release" v2.2.1, open it and press "Publish release" green button.

12) Mark release ticket in Jira as "AWAITING BUGFIX DEPLOYMENT" (depends omn the current workflow process in jira) and close it.

13) Make release in Jira and add next versions*. 

*Might have extra permissions to perform this step.

14) Annonce in Slack about a new release in the #release thread (example of message):

`edge-oai-pmh 2.2.1` has been released https://github.com/folio-org/edge-oai-pmh/releases/tag/v2.2.1

* Sometimes there is need to prepare feature release tatally form mainline. That occurs when all the latest features from development needs to be included in release. Some modules, as mod-inventory-storage for example, fall under this category. One of latest trelease was prepared with this approach - 19.3.0. maily the flow differs no so much and we mention here the main steps:

  1. Creates a long-live/release branch from mainline, if not exists before. For mentioned release 19.3.0 it was b19.3 branch.
  2. Prepare temporary release branch, tmp-release-19.3.0 for example, and do all release steps mentioned above there.
  3. After merging PR of temporary release branch (tmp-release-19.3.0 in our example) into the long-live/release - b19.3 branch we needs to update version in mainline.
  4. Create a temporary branch like the tmp_post-release_19.3.0 from master branch and increase version in pom file to the next number, in our example it will be the 19.3.1-SNAPSHOT.
  5. Merge PR of tmp_post-release_19.3.0  into the mainline.

2. Bugfix/Hotfix Releases.

This kind of release require creation (if none)  or reuse as named "long-live" branch, which contains only chnages prepared for this partucular release. Those branches has the name kind b19.2. In this description we goind to prepare build number 19.2.3 into the "long-live" branch b19.2 (needs to be create if not exists yet).

To create "long-live" branch please folow these steps: *

1) git checkout -b b19.2 v19.2.0 (creates release branch from last recent relase tag. So that this bugfix release will be based on previous general release point, i.e.  - release v19.2.0.);

2) mvn versions:set -DnewVersion=2.3.1-SNAPSHOT (here we specify version of next snapshot);

3) git commit -a -m "release branch" (commits verson chnages into new bugfix release branch);

4) git push (push changes to git stash server).

 *Some of the steps from 2 to 4 can be skipped in version in pom.xml is correct for preparing a release, if don't need to be increced (after prev. feature release, for example).


Now if we have or already prepared "long-live" branch, please follow these steps to prepare bugfix release:

1) git checkout b19.2 (switch into "long-live" release branch);

2) Create a release branch from there, for example: MODINVSTOR-524/release-19.2.3 (<release_ticket>/<release_branch_name>):

git checkout -b MODINVSTOR-524/release-19.2.3

3) Cherry pick into prevoiusly created release branch all needed commits from mainstream development branch, i.e. master. Make any extra fixes, if any changes needed, and commit them into previously created release branch*.

git cherry-pick <commit_hash>

*Don't forget to back porting extra fixes into mainstream development branch, i.e. master, if these changes valuable not only for particular bugfix release.

4) vi NEWS.md (edits release notes file and add description of release's features. Example below)

5) git commit -m "Update NEWS" NEWS.md (edits release notes file and add description of release's features. Example below):

## 19.2.3 2020-06-25

* Change permissions location for oai-pmh view (MODINVSTOR-524)

6) mvn versions:set -DnewVersion=19.2.3-SNAPSHOT (here we set the version of bugfix release, it conists of preparing relese's number with added prefix: "-SNAPSHOT") *;

6.1) commit version number changes made in the pom.xml file:

git commit -a -m "Prepare for next development iteration"

* This step can be skipped if pom.xml currently contains correct number of preparing release.

7) mvn --batch-mode -DautoVersionSubmodules=true release:clean release:prepare (runs maven release buld process. Here release number and rest of data set up automatically without any dialogs, based on version's set from previous step);

8) git push origin MODINVSTOR-524/release-19.2.3 && git push --tags origin MODINVSTOR-524/release-19.2.3 (pushing local changes, release notes in this case, with tags to remote stash. These changes are pushed to remote "long-live" branch b19.2)

9) Go to the module's repository on GitHub and create a new "Pull request" of pushed relaese branch (MODINVSTOR-524/release-19.2.3) into the "long-live release branch - b19.2 in or case,

Wait until Pull request will be merged into "long-live" branch.

10) Create a new release's description in module repository on GitHub. For example, for mentioned MOD-INVENTORY-STORAGE module there is Release v19.2.3 created. To do so:

10.1) go to module's Code page click on the Releases link and pickup Releases tab;

10.2) click on the "Draft a new release" button and fill fields with data:

a) in the fiield "Tag version" specify release's tag number: v19.2.3 and check target branch is set to master;

b) as a release title also specify release's tag number: v19.2.3;

c) in the description field, some kind of release's description can be specified:

Change permissions location for oai-pmh view (MODINVSTOR-524)

https://folio-org.atlassian.net/browse/MODINVSTOR-524

10.3) press "Publish release" green button.

11) Run release job: 

11.1) log in to Jenkins, choose appropriate tag on the "Tags" tab (was created by push operation of the step 8th)

11.2) trigger Build Now.

Please don't forget to run jenkins build on release's tag!!!

12) Mark release ticket in Jira as "AWAITING BUGFIX DEPLOYMENT" (depends omn the current workflow process in jira) and close it.

13) Make release in Jira and add next versions*. 

*Might have extra permissions to perform this step.

14) Annonce in Slack about a new release in the #release thread (example of message):

`mod-inventory-storage 19.2.3` has been released https://github.com/folio-org/mod-inventory-storage/releases/tag/v19.2.3