Mainline Release for Inclusion in Distributions

Mark the release issue as in-progress in JIRA, make sure it has the expected fix version
Create a temporary branch for the release from the head of the mainline (usually named master). The name should include the JIRA issue identifier and the version to be released, e.g MODUSERS-245-release-17-3-0
Check that the current version (as a pre-release) matches the intended release version e.g. 17.3.0-SNAPSHOT matches 17.3.0
Update the news.md file with changes included in the intended version that are relevant to the users or operators of the system e.g. changes to interfaces provided or required. Where relevant, each line should include a reference to a JIRA issue. Also make sure to remove the "IN-PROGRESS" and put in the date of release.
(Optional) replace the issue identifiers in the news with links. Adam Dickmeiss provided a script to do this:
1. ```
sed -E -i "s@([ (])([A-Z]{2,}-[0-9]{1,})([ )])@\1[\2](https://issues.folio.org/browse/\2)\3@g" NEWS.md
```
Run mvn release:prepare locally, remember to change the next release version to the next minor version e.g. 17.4.0 instead of patch version as suggested
1. It's possible for problems with the pomfile to surface at this stage, such as the use of snapshot dependencies. You may wish to do a dryrun of the prepare first (there are instructions for doing this in the maven docs). If problems do surface, back up and issue the fixes as a separate PR, then restart the release process when they are merged into main.
Compare the branch to the head of mainline, making sure that the news and next version are as expected
Raise a pull request for the temporary branch e.g. for mod-users 17.3.0
Only when the branch and pull request builds have succeeded, push the tag generated by the release preparation
Build the release tag in Jenkins e.g. for mod-users 17.3.0
Create a github release including the changes from the news file e.g. for mod-users 17.3.0
Merge the pull request (and delete the temporary branch)
Check the mainline build of the module after merge (if this fails, it can cause environment build failures due to trying to use the release version rather than next snapshot)
Mark the version as released in JIRA. Should include link to github release. Will need to override open issues as the release issue will still be open
Create new patch (e.g. 17.3.1 ) and minor (e.g. 17.4.0 ) or major (e.g. 18.0.0 ) versions for potential future releases (as not all developers have permissions to create versions)
Announce the release in #releases Slack channel, including a link to the github release e.g. for mod-users 17.3.0
Close the release issue in JIRA

What changes are included in the release?

Compare the Current Head of Mainline to the Last Release

The last release in this case refers to the last mainline release (and not intermediary patch fix releases)

This can be done using the github UI, e.g. https://github.com/folio-org/mod-users/compare/v17.2.0...master

This is primarily intended to reveal:

what provided interfaces changes have been made (both the interface versions and the changes to the interface definition)
what dependencies have changed
whether the modules configuration has changed e.g. a new version of the Tenant API

Identify which JIRA Issues are Included in the Release

Use the git log to find out what JIRA issues were included in commit messages

This can be done using the git command line interface e.g. git log --pretty=oneline v17.2.0..master | grep -e '[A-Z]\+-[0-9]\+' -o | sort -u will find all of the JIRA issues referenced in commits since the 17.2.0 release.

Use JIRA to identify the issues marked as fixed in the intended version

This can be done with a search on the intended release version e.g. the issues intended to be included in mod-users 17.3.0 can be found with this query

Analyse discrepancies between these lists

Often, the information from these two lists will not be consistent.

When an issue for the correct JIRA project is referenced in a commit and does not have a fix version, usually the version should be added
When an issue for the correct JIRA project is marked with a fix version and not included in the log, check if changes were actually made to the mainline, if not, the version should likely be removed
Some issues will have been back ported to one or more patch releases. In these circumstances, the issues should have multiple fix versions
There will typically be a release issue for the previous release included in the git log (because the pull request is merged to the mainline), this should remain unchanged

The completed list can now be used, together with the diff, to update the news for the version

Marc Johnson

Marc's Release Process for Back End Modules