A Polygene committer (normally one of the development team) should post an email to the development list proposing that a release be made and nominating a release manager. Typically, the proposer volunteers as the release manager and it passes by lazy consensus.

Clone/checkout all needed repositories, next to each other:

You should then get the following directory tree:

Ensure you can test, build Apache Polygene™ (Java Edition), including the documentation minisite generation using Asciidoc and artifact signing.

Here is what should pass before going further:

See the Build System tutorial for details.

Moreover, you will need to have a valid Jekyll installation as the Apache Polygene™ website is generated using it.

git-flow is a git extension that add git commands to easily use the git flow branching model the Apache Polygene™ project follows. See the installation instructions.

Ensure you can sign git tags.

See the Git Tools - Signing Your Work section of the Git book.

See the Apache Publishing Maven Artifacts guide and the Apache Polygene™ (Java Edition) Build System tutorial.

First, install NodeJS.

If you don’t have a npmjs.org user yet, create one now:

If your npmjs.org user is not registered as a maintainer for the generator-polygene package, ask for the privilege on dev@polygene.apache.org.

The reference KEYS file can be found at the polygene-java repository’s root, that is polygene-java/KEYS. Ensure that it contains your public key.

Next, diff it against the ones present in the dev and release distribution areas:

And update them if needed:

Resolve all issues on that version! They can be resolved by:

See the POLYGENE project on JIRA.

Apache Polygene™ release-notes are generated from JIRA issues.

Open the target Polygene™ version’s release-notes in JIRA and review them.

JIRA can produces release-notes as HTML or plain-text. Set it up to generate plain-text release-notes.

We will need these in several formats. Starting from the plain-text one we will generate the others.

First save the text-plain release-notes in a file named apache-polygene-java-<RELEASE-VERSION>-release-notes.txt. A good place for this file would be in the polygene-repos directory created earlier, alongside all repositories.

Convert to Asciidoc:

Convert to Markdown:

You should then have the following files:

We will use them later.

We use <RELEASE-VERSION>-RC# where RELEASE-VERSION is the target release version and RC# for Release Candidate and an incremental number in case the release process has to be done several times.

This will eventually generates a <RELEASE-VERSION>-RC# tag that we will amend with a <RELEASE-VERSION> signed tag if the vote passes, see below.

Make a complete build, deploying maven artifacts locally:

Review maven artifacts in distributions/build/stage/maven-binaries.

Also review the release distributions in distributions/build/distributions where you should find the following files:

If any, make the required changes, commit them and iterate.

Once you are satisfied with the produced artifacts, close the release candidate branch:

To build the release candidate bits, we need to checkout the release candidate tag, that will eventually be promoted as a signed release tag, because the Apache Polygene™ build system generates versionning information based on git metadata.

Stage artifacts to repository.apache.org :

Close the staging Nexus repository by following the Closing the staged repository guide.

Publish the new version of the generator-polygene NPM package tagged as beta:

If the release VOTE passes, we’ll remove the beta tag, making the new version available.

Then open https://www.npmjs.com/package/generator-polygene to check that the new version was published and is tagged as beta.

Source distribution, checksums and signatures must be uploaded to dist.apache.org/repos/dist/dev/polygene. This build created these in the buid/distributions directory, named apache-polygene-java-<RELEASE-VERSION>-src*.*. As this release still is a simple candidate, we’ll rename them before upload to advertise this in their names.

And then upload them:

First go downloading the release candidate distributions from dist.a.o/repos/dist/dev/polygene. Including *.MD5, *.SHA-512 and *.asc files. Put them in a directory:

Verify PGP signatures:

This must output gpg: Good signature from "Signer Name <signer@ema.il>" for each distribution.

Verify MD5 checksum:

This must output some-filename: OK for each distribution.

Verify SHA-512 checksum:

This also must output some-filename: OK for each distribution.

Unpack the source distributions, we will use the zip distribution here, both should be checked.

LICENSE & NOTICE

Review LICENSE and NOTICE file(s) ; see the Apache’s Licensing Howto.

Tools like Apache Rat™ and other projects from Apache Creadur™ can come in handy. You can also grep the whole source tree.

Build RC from sources

Create and sign the release git tag from the unsigned release candidate tag:

Push all git changes:

Promote the staged Nexus repository so it gets synched to Maven Central by following the Promoting a repo guide.

Move the release distributions, checksums and signatures from polygene-dist/dev/polygene to polygene-dist/release/polygene:

This produces one commit per file but keep svn history and runs fast, without re-uploading the distributions.

For mirrors to pick up the new bits.

Coordinate a press release with press@apache.org.

TODO

You can reuse the release-notes content from the txt/adoc/md files created earlier.

This annoucement will be used in a variety of media like emails, websites etc… Start with a text version and once satisfied create at least a Markdown version for the website, see below.

Then open https://www.npmjs.com/package/generator-polygene to check that the package is not tagged as beta anymore.

Generate the documentation and javadoc minisite:

This will automatically put all files into the polygene-website website repository.

Create a new post on the Polygene™ website by creating a new Markdown file:

You can reuse the Markdown formatted announcement content.

Add the new released version in polygene-website/site/content/java/versions.json below the latest entry:

Finally, edit polygene-website/site/src/_data/releases.yml with the new release data. Upmost is the latest:

You can run the Polygene™ website locally:

Open http://127.0.0.1:4000/ to live-preview your changes.

Once you are satisfied with the changes, build the production website:

Link /latest to the latest release:

And publish it:

Register the new release at reporter.apache.org

Finally, send an announcement to dev@ mailing list. Email announcements should have the subject line:

The announcement email should contains the release-notes as text, remember they are in the apache-polygene-java-<RELEASE-VERSION>-release-notes.txt file you created earlier.

We keep the release candidate git history. It can be useful for reviewers to have access to it. Remember, we created a release candidate branch and tags, no signed release tag.

Drop the Nexus staging repository by following the Dropping a repo guide.

Drop distributions, checksums and signatures from polygene-dist/dev/polygene

Drop NPM packages:

If a new RC is to be created, restart the process as described above.