Skip to content

Release Guide

Jump to bottom
Niklas Rentz edited this page Sep 12, 2023 · 1 revision

This document guides you through the steps needed for releasing a new version of KIELER Pragmatics.

You will need a terminal application and a user account on the RTSYS servers.

Pragmatics Release Guide

To release a new version of the KIELER Pragmatics bundles and features, please follow the following steps. They are similar to the steps for a semantics release, with some small differences:

  1. WARNING: This step is outdated! Maven requires artifacts without any .qualifier ending, which is what this script always adds. Instead, try to use the mvn org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion="x.y.z" command and manually make sure all plugins (except the external ones), features and the repo is updated.

    Set version numbers. The pragmatics plugins and features share a common version number corresponding to the current release. All plugins should have the version number of one minor version higher than the previous release (see Semantic Versioning)
    To set the version number in all pom files, manifests of all plugins and features, including their references in other files run the following script located in build/scripts/ in the pragmatics repository:

    python version.py x.x.x

    This is a good time to make sure that every plugin has a proper license file and proper metadata. Check the nightly RCA build to make sure that plugin names and provider names are set correctly.

    There are some external bundles and features in the pragmatics repository not in the schema de.cau.cs.kieler.* that are built and hosted with a pragmatics release. Their version should stay the same as where it came from. The script does not update those fixed versions, except for the build/de.cau.cs.kieler.pragmatics.repository/category.xml file. Correct the version number manually there or correct the script to exclude that file and remove this note.

  2. Check if all plug-ins to be released are contained in a feature. This is particularly important for new plug-ins.

  3. Create a release branch in the mainline repository. From this point on, the master branch can be used for normal development, while the release branch will only receive bugfixes and release-specific changes. Bugfixes are usually first developed on the master branch, and are then cherry-picked into the release branch. The branch should follow this release-branch naming scheme:

    releases/pragmatics-YYYY-MM[-##]

    The optional -## in the end is an additional consecutive number for multiple releases in the same month.

  4. Increase the version numbers on the master branch. After the release the master should have the version of the next release. This is important as it makes the nightly build on the master branch to be a snapshot for the next release and usually accelerates step 1 of the next release.

  5. Configure the build files in the repository.  The build instruction in the repository must be configured for the release build. To apply the configuration do the same thing as in this commit on the release branch. Make sure to update all associate sites to their release that you want to depend on.

  6. Test the Maven build locally. Execute the maven build locally to ensure your release-branch can build successfully to avoid needing to commit multiple 'build fixed'-commits until the branch is ready.

  7. Tell GitHub Actions to build the release. Configure the build plan Pragmatics Updatesite Release YYYY-MM of the last release to build the new one by manually triggering the workflow run. Currently this also requires manually uploading the release artifact from the release build to our server.

  8. Update top-level update site. This is done by adding the new update site URL to compositeArtifacts.xml and compositeContent.xml. These two files are in /home/kieler/public_html/updatesite.

  9. Stage the Maven artifacts by locally running this on the release branch: mvn clean deploy -P pragmatics,release (only works if you have the GPG key and Sonatype login/pw, see KLighD's release guide.

  10. On Sonatype's staging repository, make sure that you manually delete all unneeded Eclipse artifacts, that includes the repository, target platform, all features, and the test, plugins, and features folders. Only the plugins and the pragmatics artifact should remain.

  11. Release the Maven artifacts

  12. Create a tag of the release.

  13. Publish release notes and update download links as a GitHub release.

Clone this wiki locally