oasp release

Table of Contents

• Creating a Release
  • Releasing the code
    • Configure OSSRH
    • Configure PGP
    • Deploy to OSSRH
  • Releasing the documentation
  • Finalize the Release

Creating a Release

This page documents how to create and publish a release of OASP4J.

For each release there is a milestone that contains an issue for creating the release itself (what is referred to as <issue>).

Releasing the code

To release the code follow these steps.

• Create a clean clone of the repository:

  git clone https://github.com/oasp/oasp4j.git

• Ensure your repository is up-to-date:

  git pull

• Switch (from develop) to the master branch:

  git checkout master

• Merge the develop branch into master:

  git merge develop

• Ensure that the result is what you want to release (mvn clean install).

• Bump the release version by removing the -SNAPSHOT from oasp4j.version property in top-level pom.xml.

• Create an annotated tag for your release:

  git tag -a release/x.y.z -m "#<issue>: tagged x.y.z"

  e.g For release 2.5.0 the command would look like

  git tag -a release/2.5.0 -m "#618: tagged 2.5.0"

  where #618 is the issue number created for release itself under release milestone. You can confirm if the tag is created by listing out the tags with the following command

  git tag

Configure OSSRH

For publishing artifacts to OSSRH, we need an OSSRH account with necessary rights for publishing and managing staging repositories. And configure this account in Devon distribution to create connection and deploy to OSSRH.

• If you do not already have an account on OSSRH, create an account on the link below https://issues.sonatype.org/secure/Signup!default.jspa

• You need manager access to deploy artifacts to OSSRH. For same contact OASP administrators for OSSRH.

• Create a new batch file at the root of devonfw distribution with name "variables-customized.bat". Add content below to the file and save. This will override default credentials for OSSRH.

  [source,bash]
  @echo off
  rem *******************************************************************************
  rem Customized OSSRH User credentials.
  rem *******************************************************************************
  set OSSRH_USER=<ossrh_username>
  set OSSRH_PASSWD=<ossrh_password>

  Here ossrh_username & ossrh_password are the credentials used to login into OSSRH and should have rights to publish artifacts to OSSRH OASP repository.

• Open file <devon_distribution_root> > conf > .m2 > setting.xml and add a new server with following details

  <server>
     <id>ossrh</id>
     <username>${OSSRH_USER}</username>
     <password>${OSSRH_PASSWD}</password>
  </server>

  Here OSSRH_USER & OSSRH_PASSWD are OSSRH credentials configured above in file "variables-customized.bat". Id "ossrh" here points to the OSSRH repository for snaphost and release declared in OASP4J/pom.xml under "<distributionManagement>" section as shown below. "ossrh" is the default Id but please check and ascertain the Ids match.

Configure PGP

Artifacts should be PGP signed before they can be deployed to OSSRH. Artifacts can be signed either by using command line tool GnuPG or GUI based tool Gpg4win Kleopetra(preferred). Follow the steps below to sign artifacts using either of the two tools.

• Download tools GnuPg - https://www.gnupg.org/download/ gpg4win - https://www.gpg4win.org/download.html

• Installation Installation is self explanatory for GnuPG and gpg4win. To verify installation of GnuPg, open windows command line and run "gpg --version or gpg2 --version"

• Generate PGP key pair for signing artifacts.

Note	Remember the passphrase set for PGP keys as it will be used later for authentication during signing of artifacts by maven.

Using GnuPg follow either of the link below

http://central.sonatype.org/pages/working-with-pgp-signatures.html#generating-a-key-pair

https://www.youtube.com/watch?v=DE3FVty3NgE&feature=youtu.be

Using Kleopetra follow link below

https://www.deepdotweb.com/2015/02/21/pgp-tutorial-for-windows-kleopatra-gpg4win/

Exporting PGP key to public key-server

Using GnuPg - http://central.sonatype.org/pages/working-with-pgp-signatures.html#distributing-your-public-key

Using Kleopetra, click on the certificate entry you want to publish to OpenPGP certificate servers and select File > Publish on Server as shown below. These instructions are as per Kleopatra 3.0.1-gpg4win-3.0.2, for latest versions there might be some variation.

Deploy to OSSRH

• Go to the root of OASP4J project and run following command. Make sure there are no spaces between comma separated profiles.

  mvn clean deploy -P deploy,!all

• A pop will appear asking for passphrase for PGP key. Enter the passphrase and press "OK".

Note	If you face the error below, contact one of the people who have access to the repository for access rights.

• Open OSSRH, login and open staging repositories.

• Find your deployment repository as iooasp-NNNN and check its Content.

• Then click on Close to close the repository and wait a minute.

• Refresh the repository and copy the URL.

• Create a vote for the release and paste the URL of the staging repository.

• After the vote has passed with success go back to OSSRH and and click on Release to publish the release and stage to maven central.

• Switch back to the develop branch and merge from master:

  git checkout develop
  git merge master

• Edit the top-level pom.xml and change oasp4j.version property to the next planned release version including the -SNAPSHOT suffix.

• Commit and push the changes:

  git commit -m "#<issue>: open next snapshot version"
  git push

Releasing the documentation

• Initially and only once you have to create a local checkout of the github pages and of the wiki repository connected to the oasp-forge wiki:

  git clone https://github.com/oasp/oasp.github.io.git
  git clone https://github.com/oasp/oasp4j.wiki.git
  cd oasp4j.wiki
  git remote add forge https://github.com/oasp-forge/oasp4j-wiki.wiki.git

• Ensure that in the forge wiki the version is correct on the OASP4J page.

• Pull from origin as well as from forge:

  git pull origin
  git pull forge

• Carefully review all changes that have been done on the forge wiki. Potentially reject changes if necessary.

• When you are complete push your changes:

  git push origin

• In case you have rejected changes or merged content, you also need to integrate these changes back into the forge wiki.

• Build the documentation PDF as described by docgen or fetch it from the automtic jenkins build job (report and pdf located at http://oasp-ci.cloudapp.net/jenkins/job/oasp4j-wiki/ ) which runs after every change of wiki.

• Create a new folder for your version in your checkout of oasp.github.io/oasp4j (as x.y.z).

• Copy the just generated OASP4J.pdf into the new release version folder.

• Copy the index.html from the previous release to the new release version folder.

• Edit the new copy of index.html and replace all occurrences of the version to the new release as well as the release date.

• Generate the maven site from the oasp4j release checkout (see code release):

  mvn site
  mvn site:deploy

• Review that the maven site is intact and copy it to the new release version folder (from oasp4j/target/oasp4j/maven to oasp.github.io/oasp4j/x.y.z/maven).

• Update the link in the oasp4j/index.html to the latest stable documentation.

• Add, commit and push the new release version folder.

  git add x.y.z
  git commit -m "oasp/oasp4j#<issue>: released documentation"
  git push

Finalize the Release

• Close the issue of the release.

• Close the milestone of the release (if necessary correct the release date).

• Ensure that the new release is available in maven central.

• Write an announcement for the new release.