src/site/asciidoc/release-guide.adoc - incubator-retired-tamaya - Git at Google

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