Quick summary major/feature release
git checkout -b tmp-release-X.Y.0 vi NEWS.md git commit -m "Update NEWS" NEWS.md mvn -DautoVersionSubmodules=true release:clean release:prepare # Supply next feature (X.Y+1.0-SNAPSHOT) git push && git push --tags mvn release:clean |
Log in to Jenkins. Build a module from the created tag.
GitHub: Merge temporary release branch tmp-release-X.Y.0 to master.
GitHub: Update release notes.
Populate the "FixVersion" field for all Jira stories included in the release.
Create a long-live branch followed by the major and minor versions, for example, b2.17
Quick summary bug fix release
Make a bug fix on the release for the X.Y-series:
git checkout bX.Y vi NEWS.md git commit -m "Update NEWS" NEWS.md mvn --batch-mode -DautoVersionSubmodules=true release:clean release:prepare git push && git push --tags |
Log in to Jenkins. Build a module from the created tag.
GitHub: Update release notes.
Populate the "FixVersion" field for all Jira stories included in the release.
IMPORTANT
It is important to keep the SNAPSHOT version for our libraries(app-poc-tools) in the master branch with a SNAPSHOT version in pom.xml. After each release, be sure that the pom.xml contains a snapshot version and depends on the SNAPSHOT version of our libraries.
Bug fix releases
Generally, we want bug fix releases to occur in separate branches with only bug fixes (not to be confused with temporary release branches). For this purpose, we must create a long-lived release branch. We use the naming scheme b followed by the major and minor versions, for example, b2.17 which will include all bug fixes for version 2.17 (so for v2.17.1 and v2.17.2).
The bug fix release can be created as follows. Thus, it happens ONCE after a feature/major release has been performed.
Major/minor releases
Note that master represents both new features and bug fixes. If there are important new features to be added while holding back incompatible releases, then a feature branch b2 could be created. Still, it is probably not worth the effort except in exceptional cases.
Once: Ensure POM declarations
(You only need to do this once for a project. On subsequent releases you can skip this point.)
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>
|
Also, you need to add scm block with project artifactId
<scm>
<url>https://github.com/folio-org/mod-roles-keycloak</url>
<connection>scm:git:git://github.com:folio-org/mod-roles-keycloak.git</connection>
<developerConnection>scm:git:git@github.com:folio-org/mod-roles-keycloak.git</developerConnection>
<tag>HEAD</tag>
</scm>
|
Commit all changes to the POM file.
Make a temporary 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 "tmp-release-X.Y.Z" |
Optional: Update any scripts and descriptors for the release version
Update version numbers in places that Maven will not do automatically, to be 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 from templates. Note that scripts can enable the module without mentioning any version numbers.
Commit any such changes:
git commit -a -m "Towards version X.Y.Z" |
Update information in the NEWS.md
Add details about all user stories included in the release to the "NEWS.md" file.
Follow the next format for the news file:
## Version `v1.4.6` (24.09.2024) * Added dynamic permission mapping (MODROLESKC-210) * Extend Okapi mapping overrides (MODOKAPFAC-4) --- ## Version `v1.4.5` (30.08.2024) * Implement async migration (MODROLESKC-207)
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 is mostly fine. Your release tag must be prefixed with ‘v’ (the default) and you can always change the next SNAPSHOT version later if necessary.
For the question about the next post-release “new development version”, rather than accepting the default which suggests an increment of the “patch” version, instead, specify the next “minor” version. For example 2.18.0-SNAPSHOT rather than 2.17.1-SNAPSHOT
Assuming there are no build errors, you are ready to push your changes to GitHub and delete the release.properties and pom.xml.releaseBackup files.
git push && git push --tags mvn release:clean |
Build and release artifacts
After preparing the release as explained above, the next step is done via Jenkins. Jenkins credentials utilize the GitHub authentication for developers, so ensure that you are logged in to GitHub to then enable login to Jenkins.
Choose the module and go to the tags tab. Trigger a build for the version that should be released.
As a result, you should see that your build name will only contain the version of the module (e.g. 1.0.0 or 1.1.0).
Merge the temporary release branch into the 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. Select Draft a new release. Choose the tag of the new release and the previous tag. Click on the “generate release notes” button.
