= Creating an official Apache James release

Read details about http://www.apache.org/dev/publishing-maven-artifacts.html[Publishing Maven releases to Maven Central Repository]

In short, just follow the 'standard' process:

* prepare pom for release
* publish snapshot
* prepare release
* stage the release for a vote (don't forget to close the staging repository)
* vote
* release

Don't forget to add your key to https://downloads.apache.org/james/KEYS

    $ ssh people.apache.org
    $ cd /www/www.apache.org/dist/james

== Release cheat sheet

First, discuss your intention to perform a release on server-dev mailing list, to ensure a consensus would be reached
before starting this time-consuming process.

Then you can prepare the release materials:

 * Ensure the `CHANGELOG.md` and `upgrade-instructions.md` files are up to date.
 * Freeze your version in it and initiate a new iteration.
 * Write a blog post within `/src/homepage/_post` about your release.
 * Update the documentation website `/docs`, `src/site`, and `README.md` to point to your new release.
 * Update the `/dockerfiles`

Open a pull request to validate the changes.

=== Running a maven release

Once merged, it is time for the maven release.

Set up your maven configuration in `~/.m2/settings.xml` :

[source,bash]
----
<settings>
  <servers>
    <server>
      <id>apache.snapshots.https</id>
      <username>apacheId</username>
      <password>xxxxxx</password>
    </server>
    <!-- To stage a release of some part of Maven -->
    <server>
      <id>apache.releases.https</id>
      <username>apacheId</username>
      <password>xxxxxxxx</password>
    </server>
    <server>
      <id>svn.apache.org</id>
      <username>apacheId</username>
      <password>xxxxxx</password>
    </server>

  </servers>
</settings>
----

Ensure that released branch HEAD have a clean green build on the CI.

Run these commands to perform a release, from the master branch:

[source,bash]
----
mvn clean install -DskipTests -Djib.skip -Dmaven.javadoc.skip=true -T 4

mvn deploy -DskipTests -Dskip.jib -Dmaven.javadoc.skip=true -T 8

mvn release:clean

mvn release:prepare -Darguments="-Dmaven.javadoc.skip=true -DskipTests -Dskip.jib" -DautoVersionSubmodules=true

mvn release:perform -Darguments="-Dmaven.javadoc.skip=true -DskipTests -Dskip.jib" -DautoVersionSubmodules=true
----

Failure to react when being prompted for git or GPG credentials might abort the release. GPG agent with a reasonable session time can be used to unlock the key before hand and reduce this risk.

Then visit https://repository.apache.org/#stagingRepositories[Apache maven repository], go in staging repository, close
the corresponding artifact before performing the vote.

=== Voting procedure

Send the following voting template on the server-dev mailing list to call the vote:

[source]
----
Subject: Call for vote: Apache James x.x.x

Hi,

I would like to propose a new vote for x.x.x release of the Apache James server.

You can find:

 - The maven release staged in repository.apache.org as the
artifact #xxx:
https://repository.apache.org/content/repositories/orgapachejames-xxx/
 - The changelog for
x.x.x:
https://github.com/apache/james-project/blob/master/CHANGELOG.md
 - The compatibility instructions/upgrade
recommendation:
https://github.com/apache/james-project/blob/master/upgrade-instructions.md#360-version

[You can comment on major changes ]

Voting rules:
 - This is a majority approval: this release may not be vetoed.
 - A quorum of 3 binding votes is required
 - The vote starts at XXXXXX xxxth of xxxxx xxxx, xxxx UTC+x
 - The vote ends at XXXXXX xxxth of xxxxx xxxx, xxxx UTC+x

You can answer to it just with +1 and -1. Down-votes may be motivated.

3 binding votes are expected move forward on this release.

Cheers,

PMC member name
----

After the voting period, do the voting aftermaths. Reply in the voting thread:

[source]
----
Hi all,

I am happy to announce you the vote for the x.x.x release did succeed.

The release received X positive votes, X of them being binding.

Thanks to all contributors, developers and committers who made this
possible!

In the coming hours, I will finalize the release process, namely:

- Publish the maven artifacts
- Upgrade the download page and the (old) website
- Announce the release

Cheers,

PMC member name
----

=== Convenience downloads for your release

Clone this SVN repository: `https://dist.apache.org/repos/dist/release/james`

Create a folder for your release:

[source]
----
mkdir server/3.x.x
cd server/3.x.x
svn add .
----

Move the release zipped data in this folder:

- The convenience ZIPs needs to be downloaded from there staged repository. This includes server/app.
- sources can be obtained from GitHub tag

I use the following script to set up the uploads:

[source]
----
% cat /usr/local/bin/auto_sig
#/bin/bash

# This quick bash scipt intend to help commiters
# preparing artifacts for SVN upload.
#
# Performs:
#  - Hashing (sha1 + sha512)
#  - Signing (main)
#  - Position SVN properties
#
# $1: file to prepare
# $2: Key footprint to use for signing

sha512sum $1 > $1.sha512
gpg -u $2 --output $1.asc --detach-sig --armor $1
svn add $1
svn propset svn:mime-type application/octet-stream $1
svn add $1.sha512
svn add $1.asc
svn propset svn:mime-type application/octet-stream $1.asc
----

Once done it is time to commit! `svn commit -m "Upload convenience artifacts for James release 3.x.x"`

The convenience binaries will then be available. Check that the links of the download page works.

Cleanup: Only supported release lines should be maintained. Archive the previous release by deleting them from `repos/dist/release` - the INFRA will automatically move them to archive:

[source]
----
svn rm 3.5.0
svn commit -m "Archive James release 3.5.0"
----

=== Push docker containers

WARNING: Docker images are not considered as an official Apache release materials yet the Apache JAMES PMC members decided
to offer their community with a set of maintained docker images, for convenience.

Docker images includes:

- apache/james:memory-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/memory-app
- apache/james:jpa-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/jpa-app
- apache/james:demo-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/provisioned-app
- apache/james:cassandra-3.x.x build from https://github.com/apache/james-project/tree/master/server/apps/cassandra-app
- apache/james:distributed-3.x.x built from https://github.com/apache/james-project/tree/master/dockerfiles/server/apps/distributed-app

As a committer contact the INFRA and hand them your docker-hub account to get the permission.

=== Other steps

Once done:

 * Deploy website changes
 * Send an announce on server-user
 * Send an Apache foundation wide announce
