New Release Procedure
The following page describes the steps that must be taken when releasing the Overture tool. Please read all the steps carefully to familiarise yourself with the release procedure before you perform the release. Note that this page is an updated version of the old release procure. Essentially, the new release procedure automates most of the release tasks using scripts and introduces some additional release steps.
Before you do anything with releases, you will need a login to access http://oss.sonatype.org; get it by signing up to their issues tracker. Once that's done, ask one of the lead developers (@peterwvj or @CThuleHansen) to submit a ticket there to have your user id granted rights to publish to the org.overturetool repository on the Maven Central. This ticket is a reasonable template for this.
You will need to set up GPG per the Working with PGP Signatures page.
You will need access to Aarhus University's public build server.
Make sure you can post messages to the Overture core and users mailing lists maintained by Aarhus University.
You need to obtain a certificate store to sign the release and configure your Maven settings (stored in the settings.xml file) correctly. The certificates used for signing Overture are available on Aarhus University's Gitlab server so make sure you can access this repository. In particular, make sure your local ~/.m2/settings.xml has the filled-in version of the skeleton settings in the file overture_settings.xml in the repository.
The pom.xml files should occasionally be verified against Sonatype's requirements for projects. If this is the first time you've done a release, it is strongly suggested that you check the requirements against the pom.xml files. Even if everything checks out, it's a good exercise to familiarise yourself with the structure of the build.
This guide assumes that the next release is ${RELEASE_VER}, and the next development version is ${NEW_DEV_VER}. Note that the numbering scheme we use for development versions is x.y.z-SNAPSHOT where z is odd; and for release versions is x.y.z where z is even. This constraint is an artefact of the interaction between Maven, Eclipse, and our particular build configuration.
Please reach out the one of the lead developers in case you can't access some of the resources needed to perform the release.
The release candidate must be send out two or three weeks before the release date. This will allow for some time to test the tool and possibly send out a second release candidate, if needed. The release candidate is created by triggering the overture-development build job, which will automatically upload the release candidate to this website. The release candidate must be announced via the overturetool-core@overturetool.org mailing list. Testers are encouraged to follow the UI Testing Checklist.
At this point or at the creation of the release notes, check if there are issues with the Mergeable label that are not closed. If those were fixed and the commits merged into development, then close them.
Before performing release, the VDM examples that ship with the tool must be made available via http://overturetool.org/. In addition, you must make sure that the most recent version of the Overture User Guide is available via the documentation repository. There's a link to this guide listed on the manuals section on Overture tool's website.
Updating the website examples and making the most recent version of the user guide available can be performed by executing and following the instructions of the update-examples.sh script.
We will use the github-fetch-milestone-issues.py script to generate a template for the release note. However, this script requires a Github access token. So for this to work please create one and export it using an environment variable, for example by adding the following to your ~/.bashrc file:
export GITHUB_API_TOKEN = <your token>The script will generate release notes (e.g. ReleaseNotes_${RELEASE_VER}.md) for all closed milestones (each milestone corresponds to a release version) for which a release note does not yet exist. So for the script to work please go to Github and close the milestone associated with version ${RELEASE_VER}. Afterwards, move all open issues to some other milestone associated with a future release. By doing this, the ${RELEASE_VER} milestone. will only be associated with closed issued. Once that is done, download the github-fetch-milestones-issues.py script to the documentation/releasenotes folder.
Now, execute the script and commit the generated release note to the repository.
Next, we will specify the release version and the next development version. To to this, update the version numbers in the overture.release.properties file to match ${RELEASE_VER} and ${NEW_DEV_VER} and commit/push your pushes.
Next, we will perform the release of the tool and prepare the next development iteration according to the version numbers specified in the overture.release.properties file. This procedure is automated using the perform-release.sh script. To perform the release, download this script and place it in the root of the repository. Next, execute the script:
chmod +x perform-release.sh
./perform-release.shThe script will perform several changes to the repository. In particular, the script will add two commits that prepare (1) the release by updating all versions numbers to ${RELEASE_VER} and (2) the next development iteration by updating all version numbers to ${NEW_DEV_VER}. In addition, the script will push a Git tag Release/${RELEASE_VER} that marks the release.
Eventually the script will finish and ask you whether you wish to proceed with the release. Please inspect the changes performed by the script and make sure that they are correct. If the changes are correct, please confirm that you wish to proceed with the release by answering y (yes). Once that is done the script will proceed by deploying the Overture artefacts to Sonatype.
After the script has completed successfully, log into Sonatype's OSS Nexus server, choose Staging Repositories from the left side-menu, and scroll down to find and select the overturetool.org repository (it should be there if the script succeeded). Once selected you will need to Close then Release the repository (with a delay between them to allow the server to perform some validation and verification of the metadata). Once that has been done, the core jars are released. A video tutorial demonstrating how to release in Sonatype's OSS Nexus server is available here:
Next, we will release the Overture IDE to Bintray. Essentially, this will enable users to use Eclipse's self-update feature to upgrade Overture.
To release the IDE to BIntray, check out the master branch and merge the release tag Release/${RELEASE_VER} and then push your changes. Next, trigger the overture-master build job on Aarhus University's public build server. In particular, this build job will run a script that automates the release of the IDE. Once the build job has finished, you can check that the release of the IDE to Bintray was successful by upgrading an old release of Overture to the new release via the Eclipse update feature.
Next, we will announce the release on Github by:
- Drafting a new release on GitHub
- Adding the contents of the previously generated release note to the release page
- Uploading the distribution files (
target/checkout/ide/product/target/products/*.zip) and commandline jar (target/checkout/core/commandline/target/Overture-${RELEASE_VER}.jar) to the GitHub release. -
target/checkout/core/commandline/targetOverture-${RELEASE_VER}.jar
-
target/checkout/ide/product/target/products/Overture-${RELEASE_VER}-linux.gtk.x86_64.zip-
Overture-${RELEASE_VER}-macosx.cocoa.x86_64.zip- Make sure you sign the Mac app before announcing the release
Overture-${RELEASE_VER}-win32.win32.x86_64.zip
- Publish the release
Signing of the Mac app can be done using the
sign-overture.sh
script as: $(./sign-overture.sh zip <file>).
Finally, announce release via the overturetool-core@overturetool.org and overture-users@overturetool.org mailing list.