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.
As agreed by the Steering Group, VIVO follows the Semantic Versioning guidelines - http://semver.org/
To make sure release day goes smoothly, you should ensure that:
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>YourKeyName</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>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).
hkp://pgp.mit.edu
, as this is the Key Server Sonatype uses for verification: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" line
gpg --list-keys
The test plan should also be ready prior to code freeze.
Create a release candidate branch, release testing wiki page and notify developers to test.
RC_VERSION=1.10.0 |
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 <develop -or- maintenance-branch> git pull git push origin <develop -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 |
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/
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:
mvn -DaltDeploymentRepository=sonatype-nexus-snapshots::default::https://oss.sonatype.org/content/repositories/snapshots/ deploy -DskipTests |
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".
Create a new tab in the VIVO modules release plan spreadsheet.
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.10.0 NEXT=1.11.0-SNAPSHOT |
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
mvn release:prepare -DreleaseVersion=$CURR -DdevelopmentVersion=$NEXT -DautoVersionSubmodules=true -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 git checkout $REPO-$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/
Release the build artifacts to the Sonatype repository.
mvn release:perform -DperformRelease -Dgoals=deploy |
As before, your GPG passphrase may not be masked in terminal.
|
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. |
Click Staging Repositories in left navigation
Search for "vivoweb" in upper right search box (project will not have $REPO in title)
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.
The release branch has changes made since code freeze. It also contains the update to the version numbers for future development.
git checkout rel-${CURR}-RC # this is your local copy of the release branch git log |
Ensure that your commit history matches the release branch's commit history, except for the two additional commits.
If this appears correct, you can push your release branch on to the maintenance branch.
git push origin rel-${CURR}-RC:rel-${CURR[major.minor]}-maint |
git checkout develop git pull git checkout rel-${CURR}-RC git rebase -i develop git push origin develop |
#Examples #For vivo, vitro, vivo languages, vitro languages git tag #view list of tags to verify git tag -d rel-1.10.0-RC-1 git push origin :refs/tags/rel-1.10.0-RC-1 #For jenatools git tag #view list of tags to verify git tag -d rel-1.2.0-RC-1 git push origin :refs/tags/rel-1.2.0-RC-1 #For orcid-api-client-0.6.3 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 |
Let Mike Conlon know that the release is complete and can be announced.