Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

Prerequisites

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

Semantics Release Guide

To release a new version of the KIELER Semantics features and product, please follow these steps:

  1. Increase plug-in Set version numbers. Since 0.12.0 the semantics plugins and features no longer have individual version numbers. This applies to all plug-ins that have been part of the previous release in their MANIFEST.MF and pom.xml files. To that end, take a look at the changes performed on each one of them since then. For the moment, we'll leave the major version number (the first number) alone. If there have been breaking API changes (a method added to or removed from a public interface, changed public method signatures, removed public methods, that sort of thing), you will want to increase the minor version number (the second number). If there were any changes that didn't break the API, increase the revision number (the third number). There is one other case for changing the minor version number: if an important dependency has changed. For instance, regenerating Xtend-based code with a new version of Xtend will justify increasing the minor version number. If the dependency only concerns a KIELER component, however, increasing the revision number will suffice. In such cases, we just assume that users will update the plugin on which we depend anyway.

    Info

    TODO: Document how to download the most recent release update site, set that as the baseline API in Eclipse and activate the API Tools Setup to be able to update versions.

    Info

    Instead all plugins share the version of the corresponding release.
    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 semantics repository:

    Code Block
    languagebash
    python version.py x.x.x
    Info

    By the way, this is a good time to make sure that every plugin has a proper license file and proper metadata. Go check the nightly RCA build to make sure that plugin names and provider names are set correctly. Also, you may want to write down for every plugin which part of its version number was incremented – that will make the next step way easier.

  2. Increase the version numbers of all features in their feature.xml and pom.xml files. The concrete part of the version number to be increased depends on the version number increases of plug-ins included in the feature.
  3. Include all plug-ins to be released

  4. Check if all plug-ins to be released are contained in a feature. This is particularly important for new plug-ins.
    Your can use the sanity check script to check the feature containment:

    Code Block
    languagebash
    python sanity.py
  5. Update the

    feature version numbers in the product files. We currently have two product files that depend on specific versions of our features: kieler.product (part of the core.product plugin) and kwebs.product (part of the kwebs.server plugin). Open both inside Eclipse and update the version numbers of the features they include, if one of them is to be released. Also, update the version numbers of the products themselves and don't forget to synchronize the changes (there's a button on the Overview page of the product configuration editor). Once you're finished, the product files have to be made available to the build system. Copy kieler.product to build/de.cau.cs.kieler.repository and copy kwebs.product to build/de.cau.cs.kieler.kwebs.repository. If the contents of the product icon folders have changed, these changes have to be made available to the build system as well by copying them appropriately.
  6. Update the feature version numbers in the update site repositories. The features are referenced from the category.xml files in the KIELER and KWebS update site folders (build/de.cau.cs.kieler.repository and build/de.cau.cs.kwebs.repository, respectively). Take this opportunity to also adapt the update site category names to include the proper version number of the new release.
  7. Make sure the associate sites in the update site repositories are up to date. The update sites are listed in the repository pom.xml files.
  8. Update the feature list in the SDK feature, if there is one in your project. Make sure that the list of features to be included in the SDK feature is still up to date.
  9. Update plugin dependencies to match the respective requirements. Dependencies to KIELER plugins should specify no version number. Dependencies to other plugins should be updated if any compatibility problems are known (e.g., API changes between versions). Update feature dependencies to other features and plugins according to the plugin dependencies.
    This point is actually not realistic since doing this right would require so much work that we wouldn't be able to do anything else. It has to be decided at some point what to do about this.
  10. Update the splash screen and about screen with the new version number

    splash screen with the new version number. Adjust the version number in the splash.svg in plugins/de.cau.cs.kieler.core.product/images. Export to splash.bmp (no alpha channel!) in the plugin root folder.

    Expand
    titleInfo for bmp export

    Hints for splash screen adjustments:

    Dimensions: 500 x 330 px

    If your image program offers a choice, such as GIMP 2.8.10 does, it is important to save the bmp WITHOUT color space information saved or, else, the splash screen will not be displayed on Windows .... apparently a silent failure to read a "modern" BMP file (watch bug 439573). And use care, since in Gimp anyway, the choice is a negative check-off: Do not write color space information is unchecked by default, but must be checked to save the bmp WITHOUT color space information -- just like it says, but as I repeatedly misread.

    Also, The bitmap should be saved in 24-bit format (8R, 8G, 8B) for else "funny colors" (such as red instead of blue, or green instead of blue) will sometimes appear if the 32-bit format is used, with 8 bits of "transparency".
    Taken from: https://wiki.eclipse.org/Platform-releng/Updating_Branding

  11. 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.
  12. Increase the version numbers on the master branch. After the release the master should have the version of the next release. Also adjust the splash screen. (Usually accelerates step 1 and 3 of the next release)
  13. Configure the build files in the repository.  The build instruction in the repository must be configured for the release build. To apply the configuration run the following script located in build/scripts/:

    Code Block
    languagebash
    python configure.py -release x.x.x
    Info

    This script is also capable of configuring the repository for a nightly build, to force correct configuration or revert effects of a release cofiguation.

  14. Tell Bamboo to build the release. Configure the build plan of the last release to build the new one. Change the following settings:

    • Build Repository (corresponding release branch)
    • semanticsReleaseVersion Variable
    • Plan name
  15. Publish a few release candidates for testing. Test! One aspect of testing is to assign demo videos to everyone to walk through. Make sure to create tickets for them so that everyone records his findings somewhere.
  16. Proclaim a commit freeze on the release branch. Once all tickets are fixed, no one has any business pushing stuff into the release branch anymore!
  17. 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.
  18. Create a tag of the release.
  19. Publish release nodes and update download links in:
  20. Close the Jira version, set the new default version, and add a new version.
  21. Create a new Stream for the release in the Oomph setup.
  22. Send the word out to the mailing list and do a release party!


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. 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:

    Code Block
    languagebash
    python version.py x.x.x
    Info

    By the way, this is a good time to make sure that every plugin has a proper license file and proper metadata. Go check the nightly RCA build to make sure that plugin names and provider names are set correctly.

    Note

    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.

    Update the update site information in the release branch. This must be done for every feature.xml file and is best done through mass search & replace. Also, the repository build folders (for instance, build/de.cau.cs.kieler.pragmatics.repository) generate an index.html file for the update sites they are generating. Change the update site metadata in the corresponding pom.xml by updating the update site version and the update site description (released update sites should have "Release" as their description, nightly build update sites should have "Nightly Build" as their description). Also update the update site version in the master branch

    The branch should follow this release-branch naming scheme:

    Code Block
    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 Bamboo to build the release.

    There are two ways to do this: either by telling the nightly RCA build plan to also build the release branch, or by copying the RCA build plan and basing it on the release branch. The latter option has the disadvantage of adding another build plan, but adds flexibility. For instance, the release RCA build could then also be triggered by checkins, which might be a good idea during the release preparations.

    Configure the build plan Pragmatics Updatesite Release YYYY-MM of the last release to build the new one. Change the following settings:

    • KIELER Pragmatics Release Repository (to the new corresponding release branch)
    • pragmaticsReleaseVersion Variable
    • Plan name
  8. Publish a few release candidates for testing. Test! One aspect of testing is to assign demo videos to everyone to walk through. Make sure to create tickets for them so that everyone records his findings somewhere.
  9. Proclaim a commit freeze on the release branch. Once all tickets are fixed, no one has any business pushing stuff into the release branch anymore!
  10. 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.Copy the RCA, KWebS, and KLay library files to /home/kieler/public_html/files. Take care to rename the files appropriately: the nightly build files don't include version information, but only a timestamp.
  11. Create a tag of the release.
  12. Write release notes for this release in Confluence.
  13. Add the release to KIELER's downloads page in our Typo3 system.Publish release nodes and update download links in:
  14. Close the Jira version, set the new default version, and add a new version.
  15. Create a new Stream for the release in the Oomph setup.
  16. Send the word out to the mailing list and do a release party!