2017-09-12

This document describes how to perform a release of Apache Tamaya API&Core and Apache Tamaya Extensions during its incubation. It contains a step by step description of each step, so everybody in the commiters’s team will be able to perform the release procedure during the incubation phase. Differences in the procedure between Tamaya API&Core and Tamaya Extensions are mentioned.

1. Prerequisites

This section describes the prerequisite which must be given to perform the release procedure.

  1. Subversion client, needed to upload the source distribution.

  2. Git

  3. A valid GPG key, needed to sign all artifacts created during the release process.

2. Performing the release

2.1. Tell the others you would proceed with the release procedure

The first step is to announce on developer mailing list that you plan to release a new version of Tamaya API&Core as well as of the Tamaya Extensions.

Take the mail template below, adapt it if necessary, an send it to dev@tamaya.incubator.apache.org.

Subject of the announcement of an upcomming release
Starting with the preparation of the next release of <<project>>
Body of the announcement of an upcomming release.
Dear all,

If there are no objections, I'll start with the first steps for
the next release of <<project>> (review, documentation,...).
It would be great to start with the release procedure next week.

Best regards,
<<your name>>

Don’t expect that everyone will response immediately as we all are very busy. So be patient with you team members. Meanwhile you can proceed with the release preparations.

2.2. Check if everything is ready

The following items must be done before you can start with the actual release process.

  1. Check if the build chains in Apache’s Jenkins of the project in to be released are fine and where are no problems with the build and quality of the project.

  2. Ensure that all JIRA issues targeting the upcomming release are resolved. If not, get in contact with the issue assignee or the reporter to check

    1. if the issue can be postponed for the next release

    2. how long it takes to resolve it and if someone can help.

2.3. Prepare the release notes

  • Create release notes and commit them to the /readme/ directory of the project. The file name of the release notes document should be ReleaseNotes-[version].html.

Tip

Ensure that you include only notes an the release notes which affect the project you are releasing. For instance a notes on an issues which affects Tamaya Extensions should not be included in the release notes of Tamaya API&Core.

2.4. Preparing the vote of the PPMC on the release

If you are sure that everything is ready for the next release you can start the vote of the PPMC on the proposed release.

Important

Keep in mind that preparing the release really means only to prepare the release by uploading it to the dev area of the distribution server of the Apache project and to a staging repository of Apache’s Nexus.

You must not publish the artifacts created during the preparation of the release until the IPMC as well as the PPMC of Apache Tamaya have approved the release.

Before you can present the proposed release to the IPMC of the Apache Incubator, the proposed release must be approved by the PPMC of the Tamaya project.

Therefore you must run a vote on the proposed release by creating a vote candidat in the Git repository of the project, uploading the source distribution to the dev area of the distribution server of the Apache project and uploading the Maven artifacts to a staging repository in Apache’s Nexus. This sounds complicated but it isn’t that complicated if you follow the steps of this guide.

In case the vote candidate does not pass the vote of the PPMC or the IPMC you can choose between canceling the current attempt for the next release or you try to fix the issues which hinders people to vote with yes. If you have choosen the second way then you have to prepare a new vote candidat.

2.5. Preparing the release without the Release Plugin

Note

We tried to use the Maven Release Plugin to increase the level of automatisation of the release process, but we were not able to get the Maven Release Plugin working as we need it for our release process. Therefore we decided not to use it.

The first step is to create a separate branch for the release canidate. The name should consist of the release version and the number of the voting candidate.

For example if you would like to run a vote for the 1.0 release of Tamaya API&Core during its incubation for the second time, the usual branch name would be vote-1.0-incubating-02.

Follow the instructions below to create the branch for the vote and to build the vote candidate.

Creating the vote branch and building the vote candidat
$ git checkout -b vote-[release version]-[attempt]                                         (1) (2)
$ export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
$ mvn versions:set versions:commit -DnewVersion=[release version] -DperformRelease=true
$ mvn clean install -DperformRelease=true -Dgpg.keyname=[key] -Dgpg.passphrase=[passphrase] (3) (4)
  1. The version number of the planed release, e.g. 0.4-incubating

  2. The number of the current vote, e.g. 03

  3. The id of your GPG key.

  4. The passphrase of you GPG key.

Now you can check the source distribution and the Maven artifacts created during the build.

If everything is correct, deploy them to a staging repository on Apache’s Nexus.

Deploying the vote candidate to Apache’s Nexus'
$ mvn deploy

After deploying the artifacts you have to check the staging repository created in Apache’s Nexus:

  1. Login to https://repository.apache.org/ and go to Staging Repositories.

  2. Check the Contents of the newly create staging repository for you release.

  3. Close the staging repository to let Nexus do its validations on the deployed artifacts.

Important
Do not release the content of the stating repository right now. Releasing means to publish the artifacts. This will be done after a successful vote of the IPMC.

If everything is correct until now, commit your local changes, create a tag for the voting candidate and push the tag and your commits to the Git repository.

Commiting the changes done for the vote candidate
$ git add -A
$ git commit -m "Release Prepare: Set release version."
$ git tag vote-[release version]-[attempt]
$ git push --tags
  1. The version number of the planed release, e.g. 0.4-incubating

  2. The number of the current vote, e.g. 03

Finally open the next development version of the project.

Set next development version of the project
$ mvn version:set versions:commit -DnewVersion=[development version]  (1)
$ git add -A
$ git commit -m "Release Prepare: Open new development version."
  1. Next development version, e.g. 0.83-incubating-SNAPSHOT

After setting the new development version you have to add the source distribution to the distribution repository at https://dist.apache.org/repos/dist/.

Important
The source distribution and all required artifacts must be added to the development directory of Apache’s distribution server. After the approvement of the release candidate by the PPMC and the IPMC they will be moved to the release directory.
Adding all needed artifacts to distribution repository
$ svn co https://dist.apache.org/repos/dist/dev/incubator/tamaya/
$ mkdir [release version]/[project]                                          (1)
$ set RELEASE_HOME=`pwd`/[release version]/[project]
$ set PROJECT_ROOT=[repository of the project]                               (2)
$ cd $PROJECT_ROOT
$ cp DISCLAIMER $RELEASE_HOME
$ cp NOTICE $RELEASE_HOME
$ cp LICENCE $RELEASE_HOME
$ cp keys/KEYS $RELEASE_HOME
$ cp $PROJECT_ROOT/cp distribution/target/*{.tar.gz,.zip,.asc} $RELEASE_HOME (3)
$ svn add [version]
$ svn add [version]/[project]
  1. We store the artifacts of Tamaya API&Core and Tamaya Extensions always in different subdirectories. So project can be either apiandcore or extensions.

  2. PROJECT_ROOT is the Git repository of the project which you want to release.

  3. This command copies both distribution archives to $RELEASE_HOME.

Additionally there must be a SHA-1 and MD5 sigature file for each distribution archive and its GPG signature (.asc). To generate them you need programs like md5 and shasum. The name of these programs might vary from system to system.

Generating the required SHA-1 and MD5 signatures
$ cd $RELEASE_HOME
$ for f in $(ls *{.tar.gz,.zip,.asc}); do shasum -a 1 $f > ${f}.sha1; md5 $f > ${f}.md5; done

After generating the signature files you can add and commit all files and artifacts of the source distribution.

Adding and commiting the source distribution
$ cd $RELEASE_HOME
$ svn add [project]
$ svn add [version]
$ svn commit --username [Apache ID]

All commited files and artifacts should be now available via https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]/[project].

3. Run the vote on the release candidate

3.1. Run the internally

The next step is to prepare the vote on dev@tamaya.incubator.apache.org. The mail must contain serveral links, e.g. a link to the source distribution and a link to the tag in the Git repository.

The following links are needed for the mail:

  1. A link to the source distribution in the dev section of the distribution repository at https://dist.apache.org/repos/dist/dev/incubator/tamaya/.

  2. A link to the tag of the release candidate, taken from https://git1-us-west.apache.org/repos/asf?p=incubator-tamaya.git;a=summary.

  3. A link to the staging repository for the release candidate of the intended relase at http://repository.apache.org/content/repositories.

  4. A link to to the rules for release votes in the Apache Voting Process document.

Take the mail template below, insert the links, an send it to dev@tamaya.incubator.apache.org.

Subject of the vote on the release candidate
[Vote] Release of [project] [version] (1) (2)
  1. Replace project by either Apache Tamaya API&Core or Apache Tamaya Extensions

  2. Replace version by the version number of the release

Body of the vote on the release candidate
[VOTE] Release of [project] [version]                                         (1) (2)

Hi,

I was running the needed tasks to get the [version] release of [project] out. (1) (2)
The artifacts available via the Apache distribution repository [1] and
also via Apache's Nexus [2].

The tag for this release candidate is available at [3] and will be renamed
once the vote passed.
Please take a look at the artifacts and vote!

Please note:
This vote is a "majority approval" with a minimum of three +1 votes (see [4]).

------------------------------------------------
[ ] +1 for community members who have reviewed the bits
[ ] +0
[ ] -1 for fatal flaws that should cause these bits not to be released, and why ...
------------------------------------------------

Thanks,
[name]

[1] [link to the source distribution]                                         (3)
[2] [link to the staging repository at Apache's Nexus]                        (4)
[3] [link to the tag in the Git repository]                                   (5)
[4] http://www.apache.org/foundation/voting.html#ReleaseVotes
  1. Replace project by the name of the project to be release, which can be Apache Tamaya API&Core or Apache Tamaya Extensions.

  2. Replease version by the version number of the intended release.

  3. Insert here the link to the source distribution of the project in the dev section of distribution repository at https://dist.apache.org/repos/dist/dev/incubator/tamaya/.

  4. Insert here the link to the staging repository for the release candidate at http://repository.apache.org/content/repositories.

  5. Insert here the link to the tag created for the release candidate in the Git repository.

Wait at least 72 hours before you close the result. If there is not enough attention at the mailing list to vote, send a nice reminder to the list. Please keep in mind that people might be simple to busy to respond on your vote.

To close the vote count all single votes and send the result as reply to your initial mail to the mailinglist by using the templates below.

Subject of the mail with the result of the vote
[Result] (was: Re: [VOTE] Release of [project] [version]) (1) (2)
  1. Replace project by the name of the project to be release, which can be Apache Tamaya API&Core or Apache Tamaya Extensions.

  2. Replease version by the version number of the intended release.

Body of the mail with the result of the vote
Thank you for voting!

X binding +1 votes (PPMC):    (1)
[list]                        (2)

Y non-binding +1 votes:       (3)
[list]                        (4)

Z -1 votes:                   (5)
[list]                        (6)
  1. Replace X by the number of positive votes by PPMC members

  2. Replace list by the names of PPMC members with a positive vote

  3. Replace Y by the number of non-binding positive votes by non-PPMC members

  4. Replace list by the names of non-PPMC members with a positive vote

  5. Replace Z by the number of negative votes by PPMC members

  6. Replace list by the names of PPMC members with a negative vote

After the vote on the PPMC has been finished and is successful, repeat the voting process on the incubator mailing list.

3.2. Let the IPMC vote on the release candidate

During the incubation phase of Tamaya, each release must be approved by the IPMC.

The first step is to subscribe to the mailinglist general@incubator.apache.org. More information and how to do this can be found on https://incubator.apache.org/guides/lists.html.

The mail, which must be send to the list, is quite similar to the one for the PPMC, but it must also contain a link to the mail thread of the successful vote of the PPMC. The archive of the developers mailinglist of Apache Tamaya can be found at https://lists.apache.org.

The mail to the IPMC can be composed by using these both templates:

Subject of the vote on the release candidate
[Vote] Release of [project] [version] (1) (2)
  1. Replace project by either Apache Tamaya API&Core or Apache Tamaya Extensions

  2. Replace version by the version number of the release

Body of the vote on the release candidate
[VOTE] Release of [project] [version]                                         (1) (2)

Dear IPMC members,

The Apache Tamaya project was running the needed tasks to get
the [version] release of [project] out.                                       (1) (2)

The artifacts available via the Apache distribution repository [1] and
also via Apache's Nexus [2].

The tag for this release candidate is available at [3]

The mail thread of the vote can be found at [4].

Please take a look at the artifacts and vote!

Please note:
This vote is a "majority approval" with a minimum of three +1 votes (see [5]).

------------------------------------------------
[ ] +1 for IPMC members who approve this release
[ ] +0 for IPMC members with no opinion on this release
[ ] -1 for IPMC members who reject this release, and why ...
------------------------------------------------

Thanks,
[name]

[1] [link to the source distribution]                                         (3)
[2] [link to the staging repository at Apache's Nexus]                        (4)
[3] [link to the tag in the Git repository]                                   (5)
[4] [link to the thread of the vote by the PPMC.]                             (6)
[5] http://www.apache.org/foundation/voting.html#ReleaseVotes
  1. Replace project by the name of the project to be release, which can be Apache Tamaya API&Core or Apache Tamaya Extensions.

  2. Replease version by the version number of the intended release.

  3. Insert here the link to the source distribution of the project in the dev section of distribution repository at https://dist.apache.org/repos/dist/dev/incubator/tamaya/.

  4. Insert here the link to the staging repository for the release candidate at http://repository.apache.org/content/repositories.

  5. Insert here the link to the tag created for the release candidate in the Git repository.

  6. Insert here the link to vote thread on Tamaya’s developer mailinglist for this release candidate

Send the mail to general@incubator.apache.org and let the vote run for at least 72 hours.

To close the vote count all single votes and send the result as reply to your initial mail to the mailinglist by using the templates below:

Subject of the mail with the result of the vote
[Result] (was: Re: [VOTE] Release of [project] [version]) (1) (2)
  1. Replace project by the name of the project to be release, which can be Apache Tamaya API&Core or Apache Tamaya Extensions.

  2. Replease version by the version number of the intended release.

Body of the mail with the result of the vote
Thank you for voting!

X binding +1 votes (PPMC):    (1)
[list]                        (2)

Y non-binding +1 votes:       (3)
[list]                        (4)

Z -1 votes:                   (5)
[list]                        (6)
  1. Replace X by the number of positive votes by IPMC members

  2. Replace list by the names of IPMC members with a positive vote

  3. Replace Y by the number of non-binding positive votes by non-IPMC members

  4. Replace list by the names of non-PPMC members with a positive vote

  5. Replace Z by the number of negative votes by IPMC members

  6. Replace list by the names of IPMC members with a negative vote

4. Performing the release

The actually release process can be started if the binding majority of IPMC members have approved the release candidate.

The first task is to create branch for the new release out of the branch, created for the vote on the release candidate.

4.1. Tag and branch for the release

Creating this branch requires multiple commands, as Git does not allow to simply rename a remote branch. The listing below shows which commands are needed to create a branch for the new release

Renaming the branch of the release candidate
$ git checkout master                                                  (1)
$ git branch release-[version] vote-[version]-[attempt]                (2) (3) (4)
$ git push origin release-[version]:refs/heads/release-[version]       (5)
$ git push origin :vote-[version]-[attempt]                            (6)
$ git branch -D vote-[version]-[attempt]                               (7)
$ git checkout -b release-[version] --track origin/release-[version]   (8)
  1. Switching back to master

  2. Creating a release branch out of the vote branch

  3. Replace version by the version number of the release

  4. Replace attempt by the number of the successful vote attempt

  5. Pushing the new branch under the same name to the blessed repository

  6. Delete the vote branch in the blessed remote repository

  7. Delete the branch locally

  8. Checkout the new release branch and set the corresponding remote branch as upstream branch

Now create a new tag for the release based on the exsting tag for the release candidate and delete the tag made for the release candidate:

$ git tag release-[version] vote-[version]-[attempt]                   (1) (2) (3)
$ git tag -d vote-[version]-[attempt]                                  (4)
$ git push origin :vote-[version]-[attempt]                            (5)
$ git push --tags origin                                               (6)
  1. Creating a release tag for the release

  2. Replace version by the version number of the release

  3. Replace attempt by the number of the successful vote attempt

  4. Delete the tag made for the vote locally

  5. Delete tag tag mode for the vote in the blessed remote repository

  6. Push the new tag to the remote repository

Now you can merge the new release branch with the prepared development version to master.

Merging the release branch to master
$ git checkout master
$ git merge release-[version]
$ git push origin master

4.2. Cleanup Jira

Login into Apache’s Jira and close all issues in the Tamaya project.

4.3. Release the staging repository

Login into Apaches Nexus and release to staging repository for the new release.

Then wait some minutes and check if the artifacts have become available at http://repo2.maven.org/maven2/org/apache/tamaya.

4.4. Releasing the distribution artifacts

The source distribution of the release candidate must now be moved from the dev section of the distribution repository to the release section.

An easy way to achive this is to use the svn mv command only with remote URLs. Before you move the distribution artifacts, make sure the the directory for the version of the projects exists.

Checking if the target directory exists in SVN
$ svn ls https://dist.apache.org/repos/dist/release/incubator/tamaya

If the directory does not exists, create it.

Creating the directory for the version of the release
$ svn mkdir https://dist.apache.org/repos/dist/release/incubator/tamaya/[versio]    (1)
  1. Replace version by the version number of the release.

Now move all distribution artifacts from the dev section to the release section.

Moving the source distribution to the release section with SVN
$ svn mv \
    https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]/[project] \   (1) (2)
    https://dist.apache.org/repos/dist/release/incubator/tamaya/[version]/[project]
  1. Replace version by the version number of the release.

  2. Replace project by the name of the project.

To be sure that everything wents well, perform a checkout of the SVN repository for the release section and check if everything is there.

$ svn checkout https://dist.apache.org/repos/dist/release/incubator/tamaya
$ cd tamaya
$ ls -Rlah

5. Updating the website and announcing the release

Coordindate on the developers mailinglist the update of the website for the new version and the announcement of the new version.