= Initial release process proposal

v1.2, March 28, 2018

:teamcity: http://ci.groovy-lang.org
:groovy: http://groovy-lang.org
:bintray: https://bintray.com/[Bintray]
:gradle: http://gradle.org[Gradle]

_NOTE_
****
This document captures some historical information and discussion about Groovy's release process that occurred soon after the Groovy project joined Apache.
Many of the ideas went into Groovy's current release process which involves use of a gradle build at the following repo: https://github.com/apache/groovy-release/
If any of the steps in the automated process fail, this documentation might prove useful to understand what manual rectification steps that might be needed.
****

== Background

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 {teamcity}[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_2_4_X
```

If you haven't done it already, create a token on https://github.com/settings/tokens[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 http://ci.groovy-lang.org/admin/editBuild.html?id=buildType:Groovy_BintrayIntegration_ReleasePlan[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 http://ci.groovy-lang.org/viewType.html?buildTypeId=Groovy_BintrayIntegration_ReleasePlan&tab=artifactory[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.6`.
** _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.6`.
** _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.6`

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.6[https://bintray.com/groovy/maven/groovy/2.4.6].

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_.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.6.zip.asc --detach-sign apache-groovy-src-2.4.6.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.6
|     |
|     -- distribution
|     |  |-- apache-groovy-binary-2.4.6.zip
|     |  |-- apache-groovy-binary-2.4.6.zip.asc
|     |  |-- apache-groovy-binary-2.4.6.zip.md5
|     |  |-- apache-groovy-docs-2.4.6.zip
|     |  |-- apache-groovy-docs-2.4.6.zip.asc
|     |  |-- apache-groovy-docs-2.4.6.zip.md5
|     |  |-- apache-groovy-sdk-2.4.6.zip
|     |  |-- apache-groovy-sdk-2.4.6.zip.asc
|     |  `-- apache-groovy-sdk-2.4.6.zip.md5
|     |-- sources
         |-- apache-groovy-src-2.4.6.zip
         |-- apache-groovy-src-2.4.6.zip.asc
         `-- apache-groovy-src-2.4.6.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 x.y.z!
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.6.

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

[ ] +1 Release Apache Groovy 2.4.6
[ ]  0 I don't have a strong opinion about this, but I assume it's ok
[ ] -1 Do not release Apache Groovy 2.4.6 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 PMC has successfully voted the release of Apache Groovy 2.4.6 [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:

<description 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.6
[ ] 0, I don't care
[ ] -1, because...
```

If the vote passes:

== Publish the release

* Open `https://bintray.com/groovy/maven/groovy/2.4.6` and click `Publish` on the notice message (something like `ou have 532 unpublished item(s) for this version (expiring in 21 hours)`)
* Perform Maven Central synchronization: on https://bintray.com/groovy/maven/groovy/2.4.6/view?sort=&order=#central[this page (update the link to the appropriate version)], click 'sync'. This step may take several minutes to complete.
* Update the documentation symlinks on the website. You need credentials on the server:
```
cd /var/www/docs/docs
rm -f latest
ln -s groovy-2.4.6 latest
```
* Publish to GVM. Open http://ci.groovy-lang.org/viewType.html?buildTypeId=Groovy_BintrayIntegration_GvmPublish[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 http://ci.groovy-lang.org/viewType.html?buildTypeId=Groovy_BintrayIntegration_GvmMakeDefault[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`.

* Update the https://github.com/melix/groovy-website/blob/master/site/src/site/sitemap.groovy[site map] to include the newly released version.
* Push the changes
* Wait for the http://ci.groovy-lang.org/viewType.html?buildTypeId=Groovy_Website[CI website deployment build] to complete.

== 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.6.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,

```

* Broadcast the release on GVM. Open http://ci.groovy-lang.org/viewType.html?buildTypeId=Groovy_BintrayIntegration_GvmBroadcast[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`.