This document is intended to be used and kept up to date by the VIVO Release Manager. It details the steps necessary to perform an official release of VIVO.
Before Release Day
Release Numbering Convention
As agreed by the Steering Group, VIVO follows the Semantic Versioning guidelines - http://semver.org/
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Verify release privileges
To make sure release day goes smoothly, you should ensure that:
- You have an account with commit access for the vivo-project on github. As a committer, you should already have this level of access.
- You have an account with edit privileges on the lyrasis.org Confluence wiki.
- You have an oss.sonatype.org account and have requested to be given permission to publish to the org.vivoweb groupId by adding a comment to the VIVO Sonatype Hosting Ticket
- You have project configuration privileges on JIRA (you'll see an error here if you don't) : must be added to `Project Settings → Administrators` role
Update Maven settings.xml
Vitro and VIVO root pom.xml already has the correct staging and snapshot repositories listed in the OSS parent's '<distributionManagement>' section. In order to deploy, you will need to add your Sonatype OSS username and password to your local ~/.m2/settings.xml
file. For example:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <id>ossrh</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <gpg.keyname>YourKeyID</gpg.keyname> <gpg.passphrase>YourKeyPassphrase</gpg.passphrase> <gpg.defaultKeyring>false</gpg.defaultKeyring> <gpg.useagent>true</gpg.useagent> <gpg.lockmode>never</gpg.lockmode> <gpg.homedir>YourGPGDir</gpg.homedir> <gpg.publicKeyring>YourGPGDir/pubring.gpg</gpg.publicKeyring> <gpg.secretKeyring>YourGPGDir/secring.gpg</gpg.secretKeyring> </properties> </profiles> <servers> <!--Login info for Sonatype SnapShot repository--> <server> <id>ossrh</id> <username>YourSonatypeUsername</username> <password>YourSonatypePassword</password> </server> <server> <id>sonatype-nexus-snapshots</id> <username>YourSonatypeUsername</username> <password>YourSonatypePassword</password> </server> <server> <id>github</id> <username>your-github-id</username> <password>your-github-pwd</password> </server> </servers> </settings>
If you don't yet have a ~/.m2/settings.xml
file, you should create one, and copy the full contents above (obviously make sure to put in your username and password, and GPG details).
Ensure you have a trusted code signing key
- create one if you haven't before
- ensure that it's listed within the contributor keys
- You must generate and publish your own personal Code Signing Key (required by Sonatype). Here are two sites that give hints on how to do that:
- Creating a Code Signing Key
- How to Generate PGP Signatures with Maven (required for all Sonatype releases)
- Make sure to publish your Key file to
hkp://pgp.mit.edu
, as this is the Key Server Sonatype uses for verification:- (e.g.)
gpg --keyserver hkp://pgp.mit.edu --send-keys [yourKeyID]
[yourKeyId]
can be found by running the following command and copying the alpha-numeric string after the "/" on the "pub" linegpg --list-keys
- You can see if your key is already on that Key Server by visiting http://pgp.mit.edu and searching on your name
- (e.g.)
Ensure you have a SSH key setup locally and in GitHub
- Create SSH Key
mkdir -p ~/.ssh
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keygen -t rsa -C "user.email"
- Setup on GitHub
- open the public key with this command
$ cat ~/.ssh/id_rsa.pub
and copy it. - Add the id_rsa.pub key to SSH keys list on your GitHub profile.
- open the public key with this command
Prepare and distribute test plan
The test plan should also be ready prior to code freeze.
Create release branches and begin final test phase
Create a release candidate branch, release testing wiki page and notify developers to test.
RC_VERSION=1.12.1
Using the above variable, complete the below git
commands for each module being released. The modules to be released are shown in the VIVO modules release plan. A new tab may need to be added for this release. When the steps below are complete for a specific module, change the color to green, so that others know what's been done.
NOTE: The value of RC_VERSION
will vary for each release.
git checkout <main -or- maintenance-branch> git pull git push origin <main -or- maintenance-branch>:rel-${RC_VERSION}-RC
Tag the release candidate branch
git checkout ${RC_VERSION}-RC git tag -a "rel-${RC_VERSION}-RC-1" -m "rel-${RC_VERSION}-RC-1" git push origin --tags
Script Example for Linux or MINGW64 on Windows:
#!/bin/bash # RC Script RC_VERSION=1.11.2 RC_NUM=1 git checkout develop git pull git push origin develop:rel-${RC_VERSION}-RC git checkout rel-${RC_VERSION}-RC git tag -a "rel-${RC_VERSION}-RC-${RC_NUM}" -m "rel-${RC_VERSION}-RC-${RC_NUM}" git push origin --tags # Created Branch and Tag Examples # (Branch) https://github.com/vivo-project/VIVO/tree/rel-1.11.2-RC # (Tag) https://github.com/vivo-project/VIVO/tree/rel-1.11.2-RC-1 # (Branch) https://github.com/vivo-project/Vitro/tree/rel-1.11.2-RC # (Tag) https://github.com/vivo-project/Vitro/tree/rel-1.11.2-RC-1
Some of the previous steps can be done directly into github interface as described in following tutorials:
https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
https://help.github.com/articles/creating-releases/
Optional - Deploy Snapshot Artifacts
If the release candidate is coming off of a "maintenance" branch instead of "develop", it is possible that snapshot artifacts have not been deployed to the Sonatype snapshot repository. If this is the case, Travis will fail to build.
You can check if the snapshot artifacts exist by looking for each module. For example:
https://oss.sonatype.org/content/repositories/snapshots/org/vivoweb/vitro-webapp/
If the snapshot artifacts do not exist, you can deploy them to Sonatype with the following command: (Note: "sonatype-nexus-snapshots" is the server name used in the maven settings.xml file)
mvn -DaltDeploymentRepository=sonatype-nexus-snapshots::default::https://oss.sonatype.org/content/repositories/snapshots/ deploy -DskipTests
Build resources
Once a release has been created, it should be uploaded to GitHub as a Pre-Release. A Pre-Release should be created for jenatools, Vitro, and VIVO. The name should be "Release Candidate 1 - RC_VERSION".
Release Day
Create a new tab in the VIVO modules release plan spreadsheet.
- Follow the release order of the spreadsheet plan
Variables Used
These variables will be used in the examples that follow. The exact values of $ORG
and $REPO
will vary depending on which module is being released.
ORG=vivo-project REPO=VIVO CURR=1.12.1 NEXT=1.12.2-SNAPSHOT
Github Release
Perform a clean checkout of the code from Github and prepare the release.
git clone git@github.com:$ORG/$REPO.git cd $REPO git checkout -b rel-${CURR}-RC origin/rel-${CURR}-RC # or the release branch if named differently mvn release:clean
If release:clean fails, you may need to revert the RC commit with git revert HEAD
. If the parent snapshot is not available, build an old version of VIVO to populate it locally.
Resolve dependencies and set main versions to $CURR
and dev versions to $NEXT
#For vivo languages, vitro languages, jenatools, and orcid-api-client mvn release:prepare -DreleaseVersion=$CURR -DdevelopmentVersion=$NEXT -DautoVersionSubmodules=true -DpushChanges=false #For vitro ./update-versions.sh "${CURR}" mvn -Dmessage="[maven-scm-plugin] prepare release vitro-${CURR}" scm:checkin -DpushChanges=false mvn -Dtag="vitro-${CURR}" scm:tag -DpushChanges=false ./update-versions.sh "${NEXT}" mvn -Dmessage="[maven-scm-plugin] prepare development vitro-${NEXT}" scm:checkin -DpushChanges=false #For vivo ./update-versions.sh "${CURR}" mvn -Dmessage="[maven-scm-plugin] prepare release vivo-${CURR}" scm:checkin -DpushChanges=false mvn -Dtag="vivo-${CURR}" scm:tag -DpushChanges=false ./update-versions.sh "${NEXT}" mvn -Dmessage="[maven-scm-plugin] prepare development vivo-${NEXT}" scm:checkin -DpushChanges=false
Your GPG passphrase may not be masked in terminal.
Inspect/Verify local updates:
git diff HEAD~1 git diff HEAD~2 HEAD~1
These diffs should only contain changes of version numbers (from ${CURR}-SNAPSHOT to $CURR or $CURR to $NEXT) or occasionally HEAD to the current tag name ($REPO-$CURR)
Remove your local copies of VIVO artifacts to be sure of a clean build, and build the release.
rm -rf ~/.m2/repository/org/vivoweb # for VIVO-languages use git checkout vivo-languages-$CURR # detached head state # for Vitro-languages use git checkout vitro-languages-$CURR # detached head state # for VIVO use git checkout vivo-$CURR # detached head state # for Vitro use git checkout vitro-$CURR # detached head state mvn clean install
Up until this point, all of the changes made are strictly in your local repository and working directory. From this point on, the changes you make will be visible to the world and in some cases difficult to back-out of.
Push the changes to Github.
git push origin --tags # mvn task relies on the tag, make sure it does not collide with a branch name
Go to
https://github.com/vivo-project/$REPO/releases/
- Click "Draft a new release", and update title to "Release $REPO-$CURR"
- Attach appropriate artifacts
- Attach artifact MD5 files (e.g. artifact = jena2tools-1.2.0.jar, MD5 = jenatools-1.2.0.jar.md5)
If appropriate, attach binaries and checksums that have been published to Maven Central- Click Publish Release
Sonatype Release
Release the build artifacts to the Sonatype repository.
Because VIVO and Vitro does not use the standard mvn release:prepare you will need to create a release.properties file for both. They should be saved into the base directory of their respective projects. Be sure to update the CURR and NEXT to the ones being used for this release.
#release configuration projectVersionPolicyId=default project.rel.org.vivoweb\:vivo-installer-home=1.12.1 project.dev.org.vivoweb\:vivo-home=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vivo-webapp=1.12.2-SNAPSHOT pushChanges=false project.rel.org.vivoweb\:vivo-project=1.12.1 project.rel.org.vivoweb\:vivo-api=1.12.1 project.dev.org.vivoweb\:vivo-installer=1.12.2-SNAPSHOT remoteTagging=true scm.commentPrefix=[maven-release-plugin] project.dev.org.vivoweb\:vivo-installer-webapp=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vivo-api=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vivo-project=1.12.2-SNAPSHOT scm.url=scm\:git\:git@github.com\:vivo-project/VIVO.git scm.tagNameFormat=@{project.artifactId}-@{project.version} project.rel.org.vivoweb\:vivo-installer-webapp=1.12.1 project.rel.org.vivoweb\:vivo-home=1.12.1 scm.tag=vivo-1.12.1 project.rel.org.vivoweb\:vivo-webapp=1.12.1 project.dev.org.vivoweb\:vivo-installer-home=1.12.2-SNAPSHOT exec.snapshotReleasePluginAllowed=false project.rel.org.vivoweb\:vivo-installer=1.12.1
#release configuration projectVersionPolicyId=default project.rel.org.vivoweb\:vitro-installer-home=1.12.1 project.dev.org.vivoweb\:vitro-home=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vitro-webapp=1.12.2-SNAPSHOT pushChanges=false project.rel.org.vivoweb\:vitro-project=1.12.1 project.rel.org.vivoweb\:vitro-api=1.12.1 project.dev.org.vivoweb\:vitro-installer=1.12.2-SNAPSHOT remoteTagging=true scm.commentPrefix=[maven-release-plugin] project.dev.org.vivoweb\:vitro-installer-webapp=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vitro-api=1.12.2-SNAPSHOT project.rel.org.vivoweb\:vitro-dependencies=1.12.1 project.dev.org.vivoweb\:vitro-project=1.12.2-SNAPSHOT scm.url=scm\:git\:git@github.com\:vivo-project/Vitro.git scm.tagNameFormat=@{project.artifactId}-@{project.version} project.rel.org.vivoweb\:vitro-installer-webapp=1.12.1 project.rel.org.vivoweb\:vitro-home=1.12.1 scm.tag=vitro-1.12.1 project.rel.org.vivoweb\:vitro-webapp=1.12.1 project.dev.org.vivoweb\:vitro-installer-home=1.12.2-SNAPSHOT project.dev.org.vivoweb\:vitro-dependencies=1.12.2-SNAPSHOT exec.snapshotReleasePluginAllowed=false project.rel.org.vivoweb\:vitro-installer=1.12.1
Currently the remaining projects can start with this step. While gpg.keyname isn't required if you have a global key setup it is recommended. You must skip checkstyle during a deploy.
mvn release:perform -DperformRelease -Dgoals=deploy -e -Darguments="-Dgpg.keyname=XXXXYYYYXXXXYYYY -Dcheckstyle.skip=true" or mvn release:perform -DperformRelease -Dgoals=deploy -e -Darguments="-Dcheckstyle.skip=true"
As before, your GPG passphrase may not be masked in terminal.
Point of no return
The following steps, once completed are final. They cannot be undone, revoked or altered. Only proceed if you've completed all the above steps and are absolutely certain the release is ready for publication.
Additional Warning!! If autoReleaseAfterClose is set to true in your pom.xml then if the deploy passes the automated checks it WILL release! You will not be able to back this out!
- Go to https://oss.sonatype.org/index.html (Nexus Repository Manager)
- Click on Log In (Top Right Corner) and use your ossrh id from your settings.xml file
Click Staging Repositories in left navigation under Build Promotion which will open a new tab
Search for "vivoweb" in upper right search box (project will not have $REPO in title)
- Select repository and verify that $REPO is present in the Content tab
- Look for the correct types as well - war, pom, jar, md5, asc, etc.
- Note there is sometimes a delay on larger files showing in the Repo.
- Look for the correct types as well - war, pom, jar, md5, asc, etc.
- Click Close, then Refresh, then Release
- After a few moments click into the search under Artifact Search in the left navigation and type "vivoweb"
- A new Search tab will appear with all of the org.vivoweb Release artifacts
- Verify that the new release versions are now listed
- Note there is sometimes a delay on larger files showing in the Repo.
This will publish the artifacts to the Sonatype releases repository and start the process of syncing them with Maven Central, which may take several hours. When finished, they'll be available at http://repo1.maven.org/maven2/org/vivoweb.
Push Release Branch to develop and Maintenance
The release branch has changes made since code freeze. It also contains the update to the version numbers for future development.
# this is to checkout your local copy of the release branch git checkout rel-${CURR}-RC git log
Ensure that your commit history matches the release branch's commit history, except for the two additional commits.
- Changing from SNAPSHOT version to release version. Something like [maven-release-plugin] prepare release $REPO-$CURR
- Changing from release version to next development version. Something like [maven-release-plugin] prepare for next development iteration
If this appears correct, you can push your release branch on to the maintenance branch.
Push to Maintenance branch
#For vivo, vitro, vivo languages, vitro languages, jenatools, and orcid-api-client #Needs to be completed for each project in release #Example orcid-api-client-0.6.3 would become rel-0.6-maint git push origin rel-${CURR}-RC:rel-${CURR[major.minor]}-maint
Merge into 'main' branch
#For vivo and vitro the main branch was previously develop but is now "main" #For vivo languages, vitro languages, jenatools, and orcid-api-client the main branch is was master but is now "main" #Needs to be completed for each project in release # git checkout rel-${CURR}-RC git checkout main git pull git merge heads/rel-${CURR}-RC git push origin main
Clean-up RC Tags
git tag #view list of tags to verify it exists git tag -d rel-${CURR}-RC-${RCNUM} git push origin :refs/tags/rel-${CURR}-RC-${RCNUM} #Examples #For vivo, vitro, vivo languages, vitro languages git tag #view list of tags to verify it exists git tag -d rel-1.11.1-RC-1 git push origin :refs/tags/rel-1.11.1-RC-1 #For jenatools git tag #view list of tags to verify it exists git tag -d rel-1.2.0-RC-1 git push origin :refs/tags/rel-1.2.0-RC-1 #For orcid-api-client git tag #view list of tags to verify git tag -d rel-0.6.3-RC-1 git push origin :refs/tags/rel-0.6.3-RC-1
Close the release in Jira, and create the next one
- Go to the release management page.
- For the release you just made (there should be an open package icon to the left of it)
- click the gear icon on the left and choose "release"
- enter the date you finished the release
- the package should be closed
- if you are not already listed as the release manager in the description, enter "Release Manager: your-name-here"
- Create the next release
- enter a name (ie, VIVO 4.x.y) in the form at the top, and click Add. If the release manager is known, enter that in the note.
Announce release
Let Mike Conlon know that the release is complete and can be announced.
Helpful Tips - Debugging Issues
Key Issues?
#Verify that your GPG key is in your ring gpg --list-secret-keys #If the key isn't listed import the private key your previously created gpg --import name-of-private-key.asc #List the keys again but in keyid LONG format gpg --list-secret-keys --keyid-format LONG #Take the keyid and setup git to use it as your global default. git config --global user.signingkey YYYYXXXXYYYYXXXX
Oops Issues?
#Need to delete a local RC branch with issues and start again? git branch -D rel-${CURR}-RC git fetch origin rel-${CURR}-RC git checkout -b rel-${CURR}-RC --track origin/rel-${CURR}-RC #Need to remove a tag locally and in GitHub? git tag -d vivo-${CURR} git push origin :refs/tags/vivo-${CURR}