:jbake-type: page
:jbake-status: published

:sectnums: yes

// to read before
// https://incubator.apache.org/guides/releasemanagement.html
// http://www.apache.org/legal/release-policy.html

= Apache Tamaya Release Guide

[.lead]
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.

== Prerequisites

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

["upperroman"]

. Subversion client, needed to upload the source distribution.
. Git
. A valid GPG key, needed to sign all artifacts created during
  the release process.


== Performing the release

=== 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 mailto:dev@tamaya.incubator.apache.org[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.
[listing,text]
----
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.

=== Check if everything is ready

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

. Check if the build chains in
  https://builds.apache.org/view/Tamaya/[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.
. Ensure that all
  https://issues.apache.org/jira/projects/TAMAYA[JIRA^] issues
  targeting the upcomming release are resolved.
  If not, get in contact with the issue assignee or the reporter to
  check
  .. if the issue can be postponed for the next release
  .. how long it takes to resolve it and if someone can help.


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

=== 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
https://dist.apache.org[distribution
server of the Apache project^] and to a staging
repository of https://repository.apache.org[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.

=== Preparing the release without the Release Plugin

[NOTE]
====
We tried to use the http://maven.apache.org/maven-release/maven-release-plugin/[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.

[code,text]
.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.

[listing,text]
.Deploying the vote candidate to Apache's Nexus'
----
$ mvn deploy -DperformRelease=true
----

CAUTION: If you forget the _performRelease_ flag the signature files will be missing.

NOTE: Ensure you have configured your Apache _userid_ and _password_ in your `settings.xml` for the Apache
      Nexus server (id: `apache.releases.https`). Without uploading of your artifacts will fail.


// Check if these commandline parameters are needed
// -DperformRelease=true -Dgpg.keyname=[key] -Dgpg.passphrase=[passphrase] <1> <2>

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.


[listing,text]
.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.

[listing,text]
.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.


[listing,text]
.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.


[listing,text]
.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.

[listing,text]
.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/[https://dist.apache.org/repos/dist/dev/incubator/tamaya/&#91;version&#93;/&#91;project&#93;^].


== Run the vote on the release candidate

=== Run the internally

The next step is to prepare the vote on mailto: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 http://www.apache.org/foundation/voting.html#ReleaseVotes[rules for release votes^]
   in the _Apache Voting Process_ document.

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

[listing,text]
.Subject of the vote on the release candidate
----
[Vote] Release of [project] [version] <1> <2>
----
<1> Replace _project_ by either Apache Tamaya API&amp;Core or Apache Tamaya Extensions
<2> Replace _version_ by the version number of the release

[listing,text]
.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&amp;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.

[listing,text]
.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&amp;Core_ or _Apache Tamaya Extensions_.
<2> Replease _version_ by the version number of the intended release.

[listing,text]
.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.


=== 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 pass:[<a href="https://lists.apache.org/list.html?dev@tamaya.apache.org">https://lists.apache.org</a>].

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

[listing,text]
.Subject of the vote on the release candidate
----
[Vote] Release of [project] [version] <1> <2>
----
<1> Replace _project_ by either Apache Tamaya API&amp;Core or Apache Tamaya Extensions
<2> Replace _version_ by the version number of the release

[listing,text]
.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&amp;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 pass:macro[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:

[listing,text]
.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&amp;Core_ or _Apache Tamaya Extensions_.
<2> Replease _version_ by the version number of the intended release.

[listing,text]
.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


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

=== 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

[listing,shell]
.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:

[listing,shell]
----
$ 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.

[listing,text]
.Merging the release branch to `master`
----
$ git checkout master
$ git merge release-[version]
$ git push origin master
----

=== Cleanup Jira

Login into https://issues.apache.org/jira/browse/tamaya[Apache's Jira] and
close all issues in the
https://issues.apache.org/jira/browse/tamaya[Tamaya project^].

=== Release the staging repository

Login into https://repository.apache.org/[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[^].

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

[listing,text]
.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.

[listing,text]
.Creating the directory for the version of the release
----
$ svn mkdir https://dist.apache.org/repos/dist/release/incubator/tamaya/[version]    <1>
----
<1> Replace _version_ by the version number of the release.

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

[listing,text]
.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.

[listing,shell]
----
$ svn checkout https://dist.apache.org/repos/dist/release/incubator/tamaya
$ cd tamaya
$ ls -Rlah
----


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