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/

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Verify release privileges

To make sure release day goes smoothly, you should ensure that:

1. You have an account with commit access for the vivo-project on github. As a committer, you should already have this level of access.
2. You have an account with edit privileges on the duraspace.org Confluence wiki.
3. 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
4. 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>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).

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" line 

        • gpg --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

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

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:

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.10.0
NEXT=1.11.0-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

mvn release:prepare -DreleaseVersion=$CURR -DdevelopmentVersion=$NEXT -DautoVersionSubmodules=true -DpushChanges=false

-Darguments=-Dgpg.keyname=<Your Key ID>

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

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

mvn release:perform -DperformRelease -Dgoals=deploy

-Darguments=-Dgpg.keyname=<Your Key ID>

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

1. Changing from SNAPSHOT version to release version. Something like [maven-release-plugin] prepare release $REPO-$CURR
2. 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 'develop' branch

#For vivo, vitro, vivo languages, vitro languages, jenatools, and orcid-api-client
#Needs to be completed for each project in release


git checkout develop
git pull
git checkout rel-${CURR}-RC
git rebase -i develop
git push origin develop

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

1. Go to the release management page.
2. For the release you just made (there should be an open package icon to the left of it) 
   
   1. click the gear icon on the left and choose "release"
   2. enter the date you finished the release
   3. the package should be closed
   4. if you are not already listed as the release manager in the description, enter "Release Manager: your-name-here"
3. Create the next release
   1. 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.