Skip to content

Old Release Process

Jump to bottom Edit New page
Peter W. V. Tran-Jørgensen edited this page Jun 20, 2019 · 2 revisions

Introduction

This page describes the old release procedure, which consists of a number of manual steps for releasing Overture. Although the old release procedure still works, it is recommended to use the new release procedure, which uses scripts/automation to achieve the same.

Prerequisites

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 @peterwvj or @CThuleHansen to submit a ticket there to have your userid granted rights to publish to the org.overturetool repository on 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 also need to obtain a certificate store to sign the release, and configure the settings.xml properties accordingly.

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.

The reference guide for the whole process is in Sonatype's OSSRH guide. The specific deployment guide for Maven describes a slightly different process than is described below; at some point Overture should update to the current process. In the meantime, make sure your local ~/.m2/settings.xml has the (filled-in version of) the skeleton settings are in the file overture_settings.xml in the repository.

This guide assumes that the current development version is ${OLD_DEV_VER}, 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. We also use ${NEW_DEV_VER_PLAIN} to mean the new development version without the -SNAPSHOT suffix.

Finally, all commands are executed from the root of the working tree of the code repository.

Release Candidate

Before performing an actual actual, it's necessary to produce a release candidate. The candidate is just the HEAD of development and builds for it can be grabbed from the build server. The release candidate then needs to be distributed internally via the core mailing list (overturetool-core@overturetool.org) for testing (usually a couple of weeks). Once internal testing is cleared, you can proceed with the release.

As a minimum it must be checked that the main features of the tool work - see UI Testing Checklist.

Ensuring that the codebase is ready

Start by creating the new release notes: move any open issues on GitHub that won't be fixed in the current version milestone to the next expected version milestone, and create the release notes in documentation/releasenotes (see the README.md for details), and commit & push them.

Create a fresh clone of the whole Overture repository; the simplest way of doing this is to clone it directly from GitHub; however, it is faster to clone it locally and fix the remote settings to point to GitHub (how to do the latter method is out of scope of this document). Once cloned, ensure that the correct revision is checked out into the working directory.

Run mvn -Dmaven.repo.local=repository -Pforce-download-externals to build the core libraries; setting the repo variable will use a new repository, and force a fresh download of everything. Follow that with mvn -Dmaven.repo.local=repository -Pall-platforms -f ide/pom.xml to build the Eclipse plugins.

Do not go any further unless the previous build steps succeeded completely.

The following sections needs to be updated. We have a new release script which runs release:perform and corrects the branches before pushing and releasing. The is done automatically using the task described below but such that all maven-release-plugin commits are correct and enables the maven-release-plugin to perform a single normal release or the complete repo in one-go

Code Signing

  1. Ensure that your ~/.m2/settings.xml is correctly configured with the keystore path and passwords (see the overture_settings.xml in the root of the overture repository.

Assemble keystore from existing certificats

If you need to assemble the keystore from a cert, chain and key you can do as follows:

openssl pkcs12 -export -in cert.crt -inkey private.key -certfile cert.crt -name <certificate(alias)_name> -out keystore.p12

and then make the keystore:

keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype JKS

Create self-signed keystore

keytool -genkey -alias   -keystore eclipse-signing.keystore \
-storepass PASSWORD -validity 4360

Snapshot Deployment to Sonatype

  1. Ensure that your ~/.m2/settings.xml is correctly configured with your Sonatype login details (see the overture_settings.xml in the root of the overture repository.
  2. Then do mvn -Dmaven.repo.local=repository deploy

Once the deploy has finished, that snapshot will be available via the Sonatype Maven repositories.

Releasing Core to Maven Central

Run git checkout -b release to create a new release branch to work in.

An actual release of the core libraries comes down to:

mvn -Dmaven.repo.local=repository release:clean
mvn -Dmaven.repo.local=repository release:prepare -DreleaseVersion=${RELEASE_VER} -DdevelopmentVersion=${NEW_DEV_VER}
mvn -Dmaven.repo.local=repository release:perform
  1. The first command is a straightforward clean.
  2. The second preps for a release, which involves changing pom versions, tagging the git repo, and making a few commits. Because of the way our build is split between the core, maven-managed portion and the tycho-managed ide/ subtree, we will have to move some branches around afterwards.
  3. The third actually does the build and release of the core jars --- this includes checking out the whole repository fresh from GitHub in the <repo>/target directory, then building in there.

After the release:perform step 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 release:perform step, above, 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.

<iframe width="420" height="315" src="https://www.youtube.com/embed/qCr1rBLIhf8" frameborder="0" allowfullscreen></iframe>

How to release in Sonatype's OSS Nexus server

Releasing the IDE

Now we need to get the ide/ subdirectory up to date. Start by resetting some branches (from the repo root):

git branch -f development
git checkout -B release Release/${RELEASE_VER}

This will move the main development branch pointer up to the ${NEW_DEV_VER} commit that release:prepare created, and then shift the release branch back down to the ${RELEASE_VER} version that was deployed out to Sonatype.

Then open ide/pom.xml and manually correct the parent pom version to ${RELEASE_VER}, and add a <version>${OLD_DEV_VER}</version> tag (outside the <parent> tags), then run:

mvn -Dmaven.repo.local=repository -Dtycho.mode=maven tycho-versions:set-version -DnewVersion=${RELEASE_VER} -f ide/pom.xml
git add .
git commit -m "Bump ide/ to version ${RELEASE_VER}"

That will toast the <version> tag that was just added to the pom.xml (which is fine), and update all of the relevant version numbers in the ide/ subtree.

This needs rewriting. Now there is a release profile which handles this

git checkout master
git merge --no-ff release
git tag -f Release/${RELEASE_VER}

Check ide/product/overture.product to make sure that the osgi.instance.area.default property has the value "@user.home/Documents/Overture/workspace. This should have been handled correctly by the merge of release into master and the fact that we're using --no-ff to do this.

Next, you must configure the update site for IDE so that it points to the release site instead of development. This is done by editing ide/product/src/main/resources/overture.p2.inf. Look for the following lines:

addRepository(type:0,name:Overture,enabled:false,location:http${#58}//dl.bintray.com/overturetool/overturetool/);\
addRepository(type:1,name:Overture,enabled:false,location:http${#58}//dl.bintray.com/overturetool/overturetool/);\
addRepository(type:0,name:Overture Development,enabled:true,location:http${#58}//dl.bintray.com/overturetool/overturetool-development/);\
addRepository(type:1,name:Overture Development,enabled:true,location:http${#58}//dl.bintray.com/overturetool/overturetool-development/);

Switch the 4 booleans around so that Overture becomes enabled:true and Overture Development becomes enabled:false. Commit this change.

You should now be ready to push out the release. The following git commands will then reset the Release tag and push the release branch and tag up to GitHub.

git push -f origin master Release/${RELEASE_VER}

Then it's a matter of triggering the overture-master job on the buildserver and uploading the results to various places. This includes:

  • Creating a new release on GitHub at https://github.com/overturetool/overture/releases
  • 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/target
    • Overture-${RELEASE_VER}.jar
  • target/checkout/ide/product/target/product/
    • Overture-${RELEASE_VER}-linux.gtk.x86.zip
    • Overture-${RELEASE_VER}-linux.gtk.x86_64.zip
    • Overture-${RELEASE_VER}-macosx.cocoa.x86_64.zip
      • Make sure you sign this before uploading it
    • Overture-${RELEASE_VER}-win32.win32.x86.zip
    • Overture-${RELEASE_VER}-win32.win32.x86_64.zip
  • the master job pushes the p2 repository to bintray.com making it show up in self-update

Preparing the development branch for future development

Finally, we need to prepare the development branch for future development. The use of the rebase command below looks scary, but as long as the commands above were followed precisely, this will work. The idea is to move the commit that set the versions to ${NEW_DEV_VER} in the core/ directories from behind the versioning of ide/ to after.

git checkout development
git rebase release
git branch -D release

Next we need to correct the versions in ide/ (again, but for development this time). Open ide/pom.xml and manually correct the parent pom version to ${NEW_DEV_VER}, and add a <version>${RELEASE_VER}</version> tag (outside the <parent> tags), then run:

mvn -Dmaven.repo.local=repository -Dtycho.mode=maven tycho-versions:set-version -DnewVersion=${NEW_DEV_VER} -f ide/pom.xml
git add .
git commit -m "Bump ide/ to version ${NEW_DEV_VER}"
git tag Dev/${NEW_DEV_VER_PLAIN}

The development branch should now be ready to go. Please check ide/product/overture.product and make sure that the osg.instance.area.default property is not set. Also check ide/product/src/main/resources/overture.p2.inf and make sure that the booleans are set correctly (Overture, enabled:false and Overture Development, enabled:true). If everything is ok, push delopment and the corresponding tag up to GitHub, then delete the release branch.

git push origin development Dev/${NEW_DEV_VER_PLAIN}
git push origin :release

Other things that need to be done

Regenerate examples for the overturetool.org website

Once the build process has finished, the main website must be updated to use the same examples as are present in the shipped tool. As a general rule, the website may have examples more recent than those of the current tool release, but it should not have examples older than those of the current release.

To perform the update two repositories must be cloned locally:

We will use ${DOC} and ${WEB} to refer to the root directories of the checkouts of these repositories, and we'll assume that the appropriate version is checked out.

The first step is to grab the documentation and example updates. This is done in ${DOC} by merging the editing branch into master (the master branch is used for the website examples and manuals).

git checkout master
git merge origin/editing
git push origin master

Now, generate the web-ready versions of the examples:

cd ${DOC}/examples
mvn

This will run through all of the examples and place ready-to-publish versions into ${DOC}/examples/target. Then we need to replace the examples in the website repsitory.

cd ${WEB}/download/examples
rm -r Examples-VDM*.zip VDM*
mv ${DOC}/examples/target/Examples-VDM*.zip ${DOC}/examples/target/Web/VDM* .

Once that is done, commit everything in the ${WEB}/download/examples directory and push it up to GitHub. The website at overturetool.org is built using GitHub Pages, and a push will automatically rebuild the website (within a 10 minute window, typically).

Add a custom footer
Add a custom sidebar
Clone this wiki locally