]

h1. Discuss

Send a \[DISCUSS\] email to the dev@knox list proposing a release.

h1. Prepare

In preparation for each release there are a number of sub-steps required to ensure that that the project's repository is in a suitable state for branching.

h2. Start with clean local repo
This can be a fresh clone or just a repo that has no pending changes or extraneous files in.

h2. Switch to the branch that you will branch from
In this step we need to check out the previous release branch or some other existing branch from which we will create our new one.

List existing branches:
{code}
git branch -al

* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/v0.2.0
  remotes/origin/v0.3.0
  remotes/origin/v{X.Y.Z-1}
{code}


Check out the previous 

Tag Branch Point and Branch
This step tags the point in time of when the branching starts within the remote repo.

{code}
git tag --annotate v{X.Y.Z}-branch --message "Branch point for v{X.Y.Z}"
git push origin --tags
{code}

h1. Switch to the new branch
Check out the branch that is intended for this release:
{code}

git checkout -b v{X.Y.Z}
git push --set-upstream origin v{X.Y.Z}
{code}

h1. Clone & Checkout Branch
This step does a couple things for us:
* it ensures that the branch is actually there and available
* it ensures that our local repository to work from is clean

{code}
git clone https://git-wip

git clone -b v{X.Y.Z} https://gitbox-us.apache.org/repos/asf/incubator-knox.git knox-{X.Y.Z}
cd knox-{X.Y.Z}

git checkout -t origin/v{X.Y.Z}
git pull
{code}

h2. Cherry pick previous commits from master
You can use cherry-pick to pull commits in from existing branches.

To pull the changeset for the commit at the tip of the master branch:
{code}
git cherry-pick origin/master
{code}

h2. Search for and replace all occurrences of the previous branch versions within the project's files
All build artifacts that contain the previous branch's version need to be updated with the new version to reflect this new branch

.

{code}
grep -r "0\.3\.0" .
{code}

 CHANGES

Update CHANGES with release date (Release X.Y - MM/dd/yyyy) and (if needed) add additional changelog entries.
The CHANGES file can be found in gateway-release/home

h2. Update documentation

h2. Build, Test and Push Changes
{code}
git pull
git commit --all --message "Updating branch."
ant verify
git push
{code}

h2. Create a new Jenkins job to build the release.  It should call these two commands.  It is probably best to copy the previous releases job.
Assuming that you have proper karma for creating new Jenkins jobs, you will see a link to create a new one.
From that link you will be provided a page to select how to proceed; select copy existing job.

Ensure that the following form reflects the following values within various form elements:
* maven
* -Prelease clean install
* ant post-build

Be sure to change any versions to reflect 

 candidate
{code}
ant download-candidate
{code}

h2. Sanity Test

Do some basic manual testing to see if release looks ok.  For example do and install and run through a few of the samples.

h1. Sign
{code}
ant sign-candidate
{code}

h1. Verify Signatures

Verify the hashes and signatures.  First change into the distribution directory.
{code}
cd release
{code}

Verify the signatures for both the source and binary distribution.  _Note: This assumes that gpg is installed._
{code

ant sign-candidate

cd candidate

export KNOX_VERSION={X.Y.Z}
gpg --verify knox-{X.Y.Z${KNOX_VERSION}-src.zip.asc knox-{X.Y.Z${KNOX_VERSION}-src.zip
gpg --verify knox-${KNOX_VERSION}.zip.asc knox-${KNOX_VERSION}.zip
gpg --verify knox-${KNOX_VERSION}.tar.gz.asc knox-${KNOX_VERSION}.tar.gz
gpg --verify knoxshell-${KNOX_VERSION}.zip.asc knoxshell-${KNOX_VERSION}.zip
gpg --verify knoxshell-${KNOX_VERSION}.tar.gz.asc knoxshell-${KNOX_VERSION}.tar.gz

export KNOX_VERSION={X.Y.ZX.Y.Z}.zip.asc knox-{X.Y.Z}.zip
{code}

Verify the SHA-1 hashes for both the source and binary distribution.  _Note: This assumes a Linux or MacOS environment with openssl installed._
{code}
cat knox-{X.Y.Z${KNOX_VERSION}-src.zip.shasha256 && openssl sha1sha256 knox-{X.Y.Z${KNOX_VERSION}-src.zip 
cat knox-{X.Y.Z}${KNOX_VERSION}-src.zip.shasha512 && openssl sha1sha512 knox-{X.Y.Z}.zip 
{code}

Verify the MD5 digest for both the source and binary distribution.  _Note: This assumes a Linux or MacOS environment with openssl installed._
{code}
cat knox-{X.Y.Z}-src.zip.md5${KNOX_VERSION}-src.zip
cat knox-${KNOX_VERSION}.zip.sha256 && openssl sha256 knox-${KNOX_VERSION}.zip
cat knox-${KNOX_VERSION}.zip.sha512 && openssl sha512 knox-${KNOX_VERSION}.zip
cat knox-${KNOX_VERSION}.tar.gz.sha256 && openssl sha256 knox-${KNOX_VERSION}.tar.gz
cat knox-${KNOX_VERSION}.tar.gz.sha512 && openssl sha512 knox-${KNOX_VERSION}.tar.gz
cat knoxshell-${KNOX_VERSION}.zip.sha256 && openssl sha256 knoxshell-${KNOX_VERSION}.zip
cat knoxshell-${KNOX_VERSION}.zip.sha512 && openssl md5sha512 knoxknoxshell-{X.Y.Z}-src${KNOX_VERSION}.zip
cat knoxknoxshell-${X.Y.Z}.zip.md5KNOX_VERSION}.tar.gz.sha256 && openssl md5sha256 knoxknoxshell-${KNOX_VERSION}.tar.gz
cat knoxshell-${KNOX_VERSION}.tar.gz.sha512 && openssl sha512 knoxshell-${KNOX_VERSION}.tar.gz

X.Y.Z}.zip
{code}

h1. Tag Release Candidate
{code}
git tag --annotate vX.Y.Z-rcN --message "vX.Y.Z release candidate N-rcN"
git push origin --tags

cd ..{code}

h1. Stage

Follow the instructions output by the sign step above.  Basically execute this command.

{code}
ant stage-candidate
{code}

h1. Community reviews the RC

ant download-stage verify-stage

h1. Vote

Send a \[VOTE\] email to the dev@knox list.  A template was output by the sign step above as {{target/vote.eml}}.

{code}
From: {release-manager}
To: dev@knox.incubator.apache.org
Subject: [VOTE] Release Apache Knox (Incubator) {X.Y.Z}

A candidate for the Apache Knox (Incubator) {X.Y.Z} release is available at:

http://people.apache.org/~{release-manager}/knox/{X.Y.Z}/

The release candidate is a zip archive of the sources in:

https://git-wip-us.apache.org/repos/asf/incubator-knox.git
Branch {X.Y.Z}

The SHA1 checksum of the archive is {checksum}.

Please vote on releasing this package as Apache Knox (Incubator) {X.Y.Z}.
The vote is open for the next 72 hours and passes if a majority of at
least three +1 Apache Knox (Incubator) PMC votes are cast.

[ ] +1 Release this package as Apache Knox (Incubator) {X.Y.Z}
[ ] -1 Do not release this package because...
{code}

h2. Iterate based on feedback until vote passes

h2. Once vote passes, tag the release:
{code}
git tag --annotate v{X.Y.Z}-release --message "Release of v{X.Y.Z}"
git push origin --tags
{code}

h2.

 Promote

{code}
ant promote-release
{code}

h2. Verify that the results are accessible.

mvn -Papache-release -Drepo.id=apache.releases.https deploy

mvn -Dmaven.javadoc.failOnError=false -Papache-release -Drepo.id=apache.releases.https deploy

svn delete https://distincubator/knox/

h2. Wait 24 hours for release to propagate to mirrors.

h2. Update site

Update news in src/site/src/documentation/content/xdocs/index.xml and for main lucene.apache.org site stored at [https://svn.apache.org/repos/asfdist/lucenerelease/site/]. The second change may require additional rights

h2. Create version in JIRA for release X.Y.

h2. Send announcements to the user and developer lists.

h2. Update CHANGES with header for new changes

{include:Footer}knox/${OLD_VERSION} -m "Delete Knox ${OLD_VERSION} from dist.apache.org"