Fork me on GitHub

Incubation release process

Author: Cédric Champeau

Last update: July 15, 2015 (Update after concrete release)

The goal of this document is to guide the release manager in order to perform a release under the Apache Incubator. This document, reflecting the status of incubation, is work in progress and will be adapted with regards to comments from the community, mentors and IPMC.

Initiating a release

Releases can be initiated by a committer, as long as:

  • an email has been sent to the dev mailing list, where a committer volunteers for a release

  • there’s a general agreement that a release can be done. There’s still no explicit rule telling when a new Groovy version can be released, but the history of the project shows that releases are usually done when a significant amount of bugfixes have been done justifying a release, or that new major features are ready.

  • release manager has his personal setup ready. In particular:

    • release manager can log into his people.apache.org account using SSH

    • release manager has administration privileges on the CI server

Releases are launched from the CI server. A release should never be done from a personal computer.

Preparing a release

Releases are done from the CI server, but since it will involve creating tags, branches and several commits, and that the CI server doesn’t have privileges to do it, we cannot work on the Apache Git origin. Instead, it is required that the release manager forks the repository and pushes changes to his personal fork. Given that GROOVY_2_4_X is the branch to release, upstream references Apache Git, and origin the release manager fork on GitHub, preparing for a release usually starts with:

git checkout GROOVY_2_4_X
git pull --rebase upstream GROOVY_2_4_X
git push origin GROOVY_GROOVY_2_4_X

If you haven’t done it already, create a token on your GitHub profile so that the CI server can have write access on your fork. Keep the token safe!

Setup the TeamCity release configuration

Go to the TeamCity release plan configuration and open the VCS settings. If the VCS root attached to the configuration is not your GitHub fork, attach your VCS root, or create a new VCS root if you haven’t done it already. The VCS root MUST have write access using the token authentication.

Trigger the release

Go to the Artifactory Release Management tab and fill the form appropriately:

  • groovyVersion

    • release version must be set to the version number of Groovy you are releasing. For example 2.4.4.

    • next integration version must be set to the subsequent version number of Groovy you are releasing and as it will be a development version, must end with -SNAPSHOT. For example 2.4.5-SNAPSHOT.

  • groovyBundleVersion

    • release version must be set to the OSGi bundle version number of Groovy you are releasing. For example 2.4.4.

    • next integration version must be set to the subsequent OSGi bundle version number of Groovy you are releasing and as it will be a development version, must end with .SNAPSHOT. For example 2.4.5.SNAPSHOT.

  • Checkout branch: must be set to the branch your are releasing. For example, if you are releasing a 2.4.x version of Groovy, GROOVY_2_4_X.

  • Use release branch must be checked, and it will automate the creation of a release branch. Use a branch name in the form of REL_BRANCH_2_4_3

  • Create VCS tag must be checked, and it will automate the creation of a release tag. Use a tag name in the form of GROOVY_2_4_4

  • Tag comment must be set to something useful describing the release version

  • Repository to stage the release to (Artifactory Pro): must be set to oss-release-local

  • Staging comment should be set with something useful like release of Groovy 2.4.4

Hit the release button.

Upload to Apache servers

At this point, if the release build was successful, artifacts are staging on Bintray. You must log into Bintray and download the distribution artifacts. The URL for the staging distribution should be in the form of https://bintray.com/groovy/maven/groovy/2.4.4.

Downloads of the following files are only possible if you use the (groovy-operator,<api key>) credentials. If you don’t have them please ask one of the PPMC members:

  • apache-groovy-src-version-incubating.zip

  • apache-groovy-binary-version.zip

  • apache-groovy-docs-version.zip

  • apache-groovy-sdk-version.zip

as well as the corresponding asc and md5 files. There should therefore be a total of 12 files.

Note
 at this point it is possible that the MD5 files are missing, in which cases you would have to create them locally before uploading to Apache. 
for f in `ls *.zip`; do md5sum $f > $f.md5; done

It is in general not accepted that the release is signed using the CI server key, so you must replace the signatures with your own. If you didn’t yet, add your public key to the KEYS file, then sign each zip individually. This can be done, for each file, with a command line like:

gpg --armor --output apache-groovy-src-2.4.4-incubating.zip.asc --detach-sign apache-groovy-src-2.4.4-incubating.zip

Now you are ready to upload to the dev space on dist.apache.org. First of all, please make sure your local layout looks like this:

|-- KEYS
|-- 2.4.4-incubating
|     |
|     -- distribution
|     |  |-- apache-groovy-binary-2.4.4.zip
|     |  |-- apache-groovy-binary-2.4.4.zip.asc
|     |  |-- apache-groovy-binary-2.4.4.zip.md5
|     |  |-- apache-groovy-docs-2.4.4.zip
|     |  |-- apache-groovy-docs-2.4.4.zip.asc
|     |  |-- apache-groovy-docs-2.4.4.zip.md5
|     |  |-- apache-groovy-sdk-2.4.4.zip
|     |  |-- apache-groovy-sdk-2.4.4.zip.asc
|     |  `-- apache-groovy-sdk-2.4.4.zip.md5
|     |-- sources
         |-- apache-groovy-src-2.4.4-incubating.zip
         |-- apache-groovy-src-2.4.4-incubating.zip.asc
         `-- apache-groovy-src-2.4.4-incubating.zip.md5

Then you need to perform the upload:

svn https://dist.apache.org/repos/dist/dev/incubator/groovy groovy-release
cd groovy-release
cp -r ../path/to/local/groovy/<version> .
svn add <version>
svn ci <version>

Push the tag and new HEAD

git fetch origin --tags
git push upstream GROOVY_2_4_4
git push upstream GROOVY_2_4_X

Send a [VOTE] thread

You can use the following template to send a VOTE thread on the dev@ list:

Dear community,

I am happy to start the VOTE thread for a Groovy xxx-incubating!
This release includes bugfixes for ...

The changelog for this release can be found here: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12318123&version=12331941

Tag: https://git1-us-west.apache.org/repos/asf?p=groovy.git;a=tag;h=19f70958f39f0cc5c6b4d3e9471fd297400647d2

The artifacts to be voted on are located here: https://dist.apache.org/repos/dist/dev/incubator/groovy/

Release artifacts are signed with the following key: https://dist.apache.org/repos/dist/dev/incubator/groovy/KEYS

Please vote on releasing this package as Apache Groovy 2.4.4-incubating.

The vote is open for the next 72 hours and passes if a majority of at least three +1 PPMC votes are cast.

[ ] +1 Release Apache Groovy 2.4.4-incubating
[ ]  0 I don't have a strong opinion about this, but I assume it's ok
[ ] -1 Do not release Apache Groovy 2.4.4-incubating because...

Here is my vote:

+1 (binding)

After 72h, send another email summarizing the result of the vote. If it passed, you must send another vote to general@incubator.apache.org to ask the IPMC to vote:

Hi all!

The Apache Groovy PPMC has successfully voted the release of Apache Groovy 2.4.4-incubating [1], with 6 "+1" binding votes, one "+1" non binding, no "0" votes and one "-1" vote (see the explanation below). We are now asking the IPMC to vote it too. Since it is our first release under the Apache Software Foundation umbrella, let me give a few more details:

<decription of the release>

Vote on dev list: http://mail-archives.apache.org/mod_mbox/groovy-dev/201507.mbox/%3CCADQzvm%3DzDNCxpOua3LQ1ZNo62Aq40QZM7SJwgER5MfkArWrTeA%40mail.gmail.com%3E
Result of vote on dev list: http://mail-archives.apache.org/mod_mbox/groovy-dev/201507.mbox/%3CCADQzvmn1yEMMz_ZaCL5QqqUtQJdgd0NNcy8v7BVY8Lt4Uog0Zg%40mail.gmail.com%3E
Relicensing of the documentation tracking: https://issues.apache.org/jira/browse/GROOVY-7470
Vote for relicensing the docs: http://mail-archives.apache.org/mod_mbox/groovy-dev/201506.mbox/%3CCADQzvm%3DMfajQuMxoZJmpLe%2B4W22a_MDY_dC4W%2BNMWiakEEOyNg%40mail.gmail.com%3E
Result of vote for relicensing the docs: http://mail-archives.apache.org/mod_mbox/groovy-dev/201506.mbox/%3CCADQzvmkQyOEk3ofOrnTHfnvTKO5xECY87hKAGf5pD%2BuePyA8UA%40mail.gmail.com%3E

The changelog for this release can be found here: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12318123&version=12331941

Tag for the release: https://git1-us-west.apache.org/repos/asf?p=groovy.git;a=commit;h=716b0b1bd56eeab04e4441eecc91c2cd8bfda8b6
<https://git1-us-west.apache.org/repos/asf?p=groovy.git;a=tag;h=19f70958f39f0cc5c6b4d3e9471fd297400647d2>

The artifacts to be voted on are located here: https://dist.apache.org/repos/dist/dev/incubator/groovy/

Release artifacts are signed with the following keys: https://dist.apache.org/repos/dist/dev/incubator/groovy/KEYS

Vote is open for at least 72 hours. Artifacts will be moved to dist as soon as the vote passes.

[ ] +1, release Apache Groovy 2.4.4-incubating
[ ] 0, I don't care
[ ] -1, because...

If the vote passes:

Publish the release

cd /var/www/docs/docs
rm -f latest
ln -s groovy-2.4.4 latest

  • Publish to GVM. Open the publish configuration, click on the 3 dots near run then on the parameters tab, fill in the groovyVersion parameter. Click on run build.

  • if the release is NOT a beta or a release candidate, make it the default version on GVM. Open the GVM make default configuration, click on the 3 dots near run then on the parameters tab, fill in the groovyVersion parameter. Click on run build.

Update the web site

If you don’t have it locally, checkout https://github.com/groovy/groovy-website.

Send an announcement email

You should wait 24h before doing this (in order for dist.apache.org to be properly mirrored). Send an email to dev@, user@ and announce@apache.org.

You can use this template. Please make sure that the email at least contains the DISCLAIMER:

Dear community,

We are pleased to announce the first release of Apache Groovy done under the Apache Software Foundation
Incubator sponsorship! Apache Groovy is a multi-facet programming language for the JVM. Details can be
found at http://groovy-lang.org

This release is a maintenance release of the 2.4.x branch, but contains critical fixes, in particular a fix
for a 0-day vulnerability. Details can be found on http://groovy-lang.org/security.html

It is strongly encouraged that all users upgrade to this version. There is no plan to provide patches for
older versions of Groovy which were not developped under the Foundation umbrella.

Changelog for this version can be found at: http://groovy-lang.org/changelogs/changelog-2.4.4.html
Sources can be downloaded from: http://www.groovy-lang.org/download.html
Convenience binaries, SDK and documentation can be found at: http://www.groovy-lang.org/download.html

We would like to thank all people who contributed to this release. In particular, thanks to our mentors who are
having hard days at explaining the Apache Way :) Despite comments we received about this release, we felt that
the security issue is so important that we deserved this to our community.

Best regards,

----
DISCLAIMER

Apache Groovy is an effort undergoing incubation at the Apache
Software Foundation (ASF), sponsored by the Apache Incubator PMC.

Incubation is required of all newly accepted projects until a further
review indicates that the infrastructure, communications, and decision
making process have stabilized in a manner consistent with other
successful ASF projects.

While incubation status is not necessarily a reflection of the
completeness or stability of the code, it does indicate that the
project has yet to be fully endorsed by the ASF.

  • Broadcast the release on GVM. Open the GVM broadcast configuration, click on the 3 dots near run then on the parameters tab, fill in the groovyVersion parameter. Click on run build.