12. For Core-Developers

12.1. Creating a Release

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

For each release there is a milestone that contains an issue for creating the release itself (the github issue of that issue is referred as «issue»). The release version is referred as «x.y.z».

12.1.1. Releasing the code

To release the code follow these steps.

  • Create a clean clone of the repository:

    git clone https://github.com/devonfw/devon4j.git
  • In case you want to build a (bug fix) release from a different branch, switch to that branch:

    git checkout -b develop-«x.y» origin/develop-«x.y»
  • Ensure your branch is up-to-date:

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

  • Bump the release version by removing the -SNAPSHOT from devon4j.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 devonfw 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 devonfw administrators for OSSRH.

  • Open file conf/.m2/setting.xml in your devon distribution (devon-ide) and add a new server with following details

    <server>
       <id>ossrh</id>
       <username>«ossrh_username»</username>
       <password>«ossrh_password»</password>
    </server>

    Here «ossrh_username» and «ossrh_password» are the account details used to login into OSSRH and should have rights to publish artifacts to OSSRH for groupId name com.devonfw (and its children). Please use password encryption and prevent storing passwords in plain text. The id ossrh points to the OSSRH repository for snaphost and release declared in the <distributionManagement> section of the devon4j/pom.xml.

  • Optionally you may want to explicitly define PGP key via the associated email-address:

    <profile>
      <id>devon.ossrh</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.keyname>your.email@address.com</gpg.keyname>
      </properties>
    </profile>
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.

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

Using Kleopetra follow link below

Exporting PGP key to public key-server

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.

pgp key publish
Deploy to OSSRH
  • Go to the root of devon4j project and run following command. Make sure there are no spaces between comma separated profiles.

    mvn clean deploy -P deploy
  • A pop will appear asking for passphrase for PGP key. Enter the passphrase and press "OK".

pgpkey passphrase
Note

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

ossrh publish error forbidden
  • Open OSSRH, login and open staging repositories.

  • Find your deployment repository as comdevonfw-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.

  • Edit the top-level pom.xml and change devon4j.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
  • In case you build the release from a branch other that develop ensure to follow the next steps. Otherwise you are done here and can continue to the next section. To merge the changes (bug fixes) onto develop do:

    git checkout develop
    git merge develop-«x.y»
  • You most probably will have a conflict in the top-level pom.xml. Then resolve this conflict. In any case edit this pom.xml and ensure that it is still pointing to the latest planned SNAPSHOT for the develop branch.

  • If there are local changes to the top-level pom.xml, commit them:

    git commit -m "#«issue»: open next snapshot version"
  • Push the changes of your develop branch:

    git push

12.1.2. Releasing the maven-site

  • Create a new folder for your version in your checkout of devonfw.github.io/devon4j (as «x.y.z»).

  • Copy the just generated devon4j-doc.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 devon4j 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 devon4j/target/devon4j/maven to devonfw.github.io/devon4j/«x.y.z»/maven).

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

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

    git add «x.y.z»
    git commit -m "devonfw/devon4j#«issue»: released documentation"
    git push

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

Last updated 2019-11-13 14:38:09 UTC