// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
// .
//   http://www.apache.org/licenses/LICENSE-2.0
// .
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

include::temp-properties-files-for-site/attributes.adoc[]

== Apache Tamaya -- Release Guide

Performing a release requires several steps. This document describes each step, so everybody in the committer's
team should be able to perform the release procedure.


=== Tell the others you would proceed with the release procedure

[listing,text]
----------------------------------------
    first steps for the next release

    hi @ all,

    if there are no objections, i'll start with the first steps for the next release (review, documentation,...).
    it would be great to start with the release procedure next week.

    regards,
    [name]
----------------------------------------


=== Check everything is ready

* Check the jenkins builds.
* Ensure all JIRA-tickets targeting the release are resolved. If not, get in contact with the ticket
  owner/assignee to check
  ** if the ticket can be postponed for the next release
  ** how long it takes to resolve it and if one can help.


=== Prepare the release

* Create release notes and commit them to `tamaya/readme/` (format `ReleaseNotes-[version].html`)
* Create a release branch in git and switch to this branch:


==== Using the release plugin

For performing the release you can use the maven release plugin:

[listing,text]
----------------------------------------
    git checkout -b vote-tamaya-[release version]

    export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
    mvn release:prepare -DdryRun=true -DperformRelease=true

    // optionally pass GPG params for signing with: -Darguments="-Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX"

    //copy prepared workspace (to continue faster if an upload fails in the next step)
----------------------------------------

* If something fails you may switch to the master branch, fix whatever is needed and rebase your release branch to
  accomodate the latest changes done.
* On success you can check the release packages from `dist/target`.
* If everything looks good you can proceed with the release:

[listing,text]
----------------------------------------
    export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
    mvn release:prepare -DperformRelease=true
    mvn release:perform -DperformRelease=true
----------------------------------------

==== Preparing the release without the Release Plugin

The release plugin is great, but in some cases it breaks even, when release:prepare -DdryRun=true was successful.
Preparing the release vote without the release plugin is stright forward:

* As described checkout a release branch of the current head
* Then us maven and git commands to prepare the release:

[listing,text]
----------------------------------------
    git checkout -b vote-tamaya-[release version]

    export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=200m"
    mvn versions:set versions:commit -DnewVersion=[release version] -DperformRelease=true

    // build the release locally and sign it with your certs
    mvn clean install -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX

----------------------------------------

* Check if everything is in place and correct, when finished you can tag and deploy the release...

[listing,text]
----------------------------------------
mvn deploy -DperformRelease=true -Dgpg.keyname=1336D3E6 -Dgpg.passphrase=XXXXXX
----------------------------------------

* check the created commits including user-name and email
* login to https://repository.apache.org/ and go to "Staging Repositories"
* check the contents of the newly created tamaya staging repository
* _close_ the repository to let Nexus do its validations
* On success:
* push the release-branch to the git repo

[listing,text]
----------------------------------------
git add -A
git commit -m "Release Prepare: Set release version."
git tag vote01-[release-version]
git push --tags
----------------------------------------

Finally open the next development version:

[listing,text]
----------------------------------------
# example: newVersion=0.3-incubating-SNAPSHOT
mvn version:set versions:commit -DnewVersion=[development-version]
git add -A
git commit -m "Release Prepare: Open new development version."
----------------------------------------


* Add the distribution artifacts to the dev repositories:

[listing,text]
----------------------------------------
    svn co https://dist.apache.org/repos/dist/dev/incubator/tamaya/
    mkdir [version]
    set RELEASE_HOME='pwd'/[version]
    cd PROJECT_ROOT
    cp DISCLAIMER $RELEASE_HOME
    cp NOTICE $RELEASE_HOME
    cp LICENCE $RELEASE_HOME
    cp rat.txt $RELEASE_HOME

    // Copy everything from
    //  $STAGING_REPO/distribution/0.2-incubating/tamaya-distribution-[version]-distribution-* into $RELEASE_HOME

    svn add [version]
    svn commit --username <apacheId>
----------------------------------------

* Check contents on https://dist.apache.org/repos/dist/dev/incubator/tamaya/[version]


=== Start the vote

[listing,text]
----------------------------------------
    [VOTE] Release of Apache Tamaya [version]


    Hi,

    I was running the needed tasks to get the [version] release of Apache Tamaya out.
    The artifacts are deployed to Nexus [1] (and [2]) and releases [4].

    The tag is available at [3] and will 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 [5]).

    ------------------------------------------------
    [ ] +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] https://repository.apache.org/content/repositories/...
    [2] https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-source-release.zip
        https://repository.apache.org/content/repositories/org/apache/tamaya/tamaya-distribution/[version]/tamaya-[version]-bin-release.zip
    [3] https://git1-us-west.apache.org/repos/asf?p=incubator-tamaya.git;a=commit;h=2910da468fce16210e6dd77d8ba23ddbdd434efe
    [4] https://dist.apache.org/repos/dist/dev/incubator/tamaya/[release-version]
    [5] http://www.apache.org/foundation/voting.html#ReleaseVotes
----------------------------------------

* Announce the Vote
  ** Create a short link to the release at http://s.apache.org (format Tamaya_[version])
  ** Tweet about the vote via _@TamayaConf_

* After 72 hours close the vote write a reult email, e.g.

[listing,text]
----------------------------------------
    [Result] (was: Re: [VOTE] Release of Apache Tamaya [version])

    thank you for voting!

    X binding +1 votes (pmc):
    [list]

    Y non-binding +1 votes:
    [list]

    Z -1 votes
    [list]
----------------------------------------

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


== Perform the release

If the binding majority approved the vote on both lists continue:

* Login to https://repository.apache.org/ and _release_ the repository
* Rename the vote branch:

[listing,text]
----------------------------------------
    git branch -m vote01-tamaya-[release-version] tamaya-[release-version]
----------------------------------------

* Add a release tag:

----------------------------------------
    git tag -a tamaya-[release-version]
----------------------------------------

* Merge master with the new prepared version:

[listing,text]
----------------------------------------
    git checkout master
    git merge tamaya-[release-version]
    git push origin tamaya-[release-version]
    git push origin master
----------------------------------------

* Close the release and corresponding tickets at JIRA

* Wait some minutes and check `http://repo2.maven.org/maven2/org/apache/tamaya`

* Upload the distribution Artifacts

[listing,text]
----------------------------------------
    svn co https://dist.apache.org/repos/dist/release/incubator/tamaya/
    mkdir [version]
    // add and commit the artifacts (*source-release.zip, *bin-release.zip + asc, md5, sha1)
    // use the artifacts from:
    //  http://repo1.maven.org/maven2/org/apache/tamaya/tamaya-distribution/[version]/
----------------------------------------


=== Updating the Tamaya Project Site

Basically the new site should be directly deployable, just execute

[listing,text]
----------------------------------------
mvn site site:deploy
----------------------------------------


=== Announce the new version

Announce the new version on @TamayaConf and other social media channels. Also drop a short mail on the amiling list.