Table of Contents

Prerequisites

Before entering into this process you need to ensure you will be able to cryptographically sign the final result in such a way that others can validate the signature. This can be a confusing process. Here are links to several documents that should help.

...

http://www.apache.org/dev/openpgp.html

...

http://www.apache.org/dev/release-signing.html

...

http://httpd.apache.org/dev/verification.html

Discuss

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

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.

Start with clean local repo

This can be a fresh clone or just a repo that has no pending changes or extraneous files in.

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 Block
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}

Check out the previous (release) branch:

Code Block
git checkout -t origin/v{X.Y.Z-1}

Tag Branch Point and Branch

This step tags the point in time of when the branching starts within the remote repo.

Code Block

]

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. Update CHANGES

Update CHANGES.txt 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 "Prepare for branch."
ant verify
git push
{code}

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

Switch to the new branch

Check out the branch that is intended for this release:

Code Block
git checkout -b v{X.Y.Z} git push --set-upstream origin v{X.Y.Z} {code} h1. Clone & Checkout Branch {code} git clone

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 Block

git clone -b v{X.Y.Z} https://git-wip-usgitbox.apache.org/repos/asf/incubator-knox.git knox-{X.Y.Z}
cd knox-{X.Y.Z}
git checkout -t origin/v{X.Y.Z}
{code}

h2. Update version numbers on master branch (from

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 Block
git cherry-pick origin/master

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 Block
grep -r "0\.3\.0" .

Change all occurrences as appropriate.

Update version numbers on master branch (from A.B.C-SNAPSHOT

...

to

...

D.E.F-SNAPSHOT)

...

and

...

push

...

changes

...

Update

...

version

...

numbers

...

on

...

release

...

branch

...

(from

...

A.B.C-SNAPSHOT

...

to

...

A.B.C)

...

and

...

push changes

Update CHANGES

Update documentation

Build, Test and Push Changes

Code Block

 changes

{code}
git pull
git commit --all --message "PrepareUpdating for 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.
mvn -Prelease clean install
ant post-build

h3. Download the release candidate
{code}
ant download-candidate

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

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.

New Jenkins 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.

The Copy from text box will auto complete as you type - start with "Knox-" and select the job to copy from.

Ensure that the following form reflects the following values within various form elements:

maven
-Ppackage,release clean install
ant post-build

Be sure to change any versions to reflect "v{X.Y.Z}"

Upon successful creation of the new job, you may manually kick off a build with the Build Now button.

Download the release candidate

You will be prompted for your Jenkins username and password.

Code Block
ant download-candidate

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.

Sign

You will be prompted for your GPG passphrase.

Code Block
ant sign-candidate

This will prompt you for your passphrase for each signed archive.

Verify Signatures

Verify the hashes and signatures. First change into the distribution directory.

Code Block
cd candidate

Verify the signatures for both the source and binary distribution. Note: This assumes that gpg is installed.

Code Block

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-${X.Y.Z}.zipKNOX_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

Verify the SHA-256 and SHA-512 hashes for both the source and binary distribution. Note: This assumes a Linux or MacOS environment with openssl installed.

Code Block

export KNOX_VERSION={X.Y.Z{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-${X.Y.Z}.zip
{code}

h1. Tag Release Candidate
{code}
KNOX_VERSION}.tar.gz
cat knoxshell-${KNOX_VERSION}.tar.gz.sha512 && openssl sha512 knoxshell-${KNOX_VERSION}.tar.gz

Tag Release Candidate

Code Block
git tag --annotate vX.Y.Z-rcN --message "vX.Y.Z release candidate N-rcN" git push origin --tags

Stage

Follow the instructions output by the sign step above. Basically execute this command. You will be prompted for your SVN username and password.

Code Block
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

Community reviews the RC

https://dist.apache.org/repos/dist/dev

...

/knox/

You will be prompted for your SVN username and password.

Code Block
ant download-stage verify-stage

Vote

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

Iterate based on feedback until vote passes

Once vote passes, tag the release:

Code Block

git tag --annotate v

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) -release --message "Release of v{X.Y.Z}"
git releasepush is available at:

http://peopleorigin --tags

Promote

You will be prompted for your SVN username and password.

Code Block
ant promote-release

Verify that the results are accessible.

https://dist.apache.org/

...

repos/dist/release/knox/

Publish to Maven Repository

Preparation

Setup your ~/.m2/settings.xml file as described here.
Make sure you encrypt your passwords as described here.

Staging

This special variant of the build command will build and publish the release to a staging are in the Apache Nexus repo.
Note: Get your gpg passphrase in your paste buffer you will need it MANY times. If someone can figure out how to use gpg-agent properly they should document it.
This page contains some information about getting gpg-agent installed and running.

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

If you have issues with the above command due to javadoc warnings, something like this can be done:

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

Release

Once that completes, login to the Apache Maven Nexus staging repositories with your Apache credentials and:

Select "Staging Repositories" from "Build Promotion" on the left.
Close the stage with the Close button at the top of the repo list. For the Description field use Apache Knox 0.5.1 Staged
Release the stage with the Release button at the top of the repo list. For the Description field Apache Knox 0.5.1 Release

Wait 24 hours for release to propagate to mirrors.

Update site

Update news in News.

Create version in JIRA for release X.Y.

Send announcements to the user and developer lists.

Update CHANGES with header for new changes

Remove old release from dist.apache.org

Code Block
svn delete https://dist.apache.org/repos/dist/release/knox/${OLD_VERSION} -m "Delete Knox ${OLD_VERSION} from dist.apache.org"

Include Page

	Footer
	Footer

Space shortcuts

Child pages

Page History

Versions Compared

Old Version 29

New Version Current

Key

Prerequisites

Discuss

Prepare

Start with clean local repo

Switch to the branch that you will branch from

Tag Branch Point and Branch

Switch to the new branch

Clone & Checkout Branch

Cherry pick previous commits from master

Search for and replace all occurrences of the previous branch versions within the project's files

Update version numbers on master branch (from A.B.C-SNAPSHOT

to

D.E.F-SNAPSHOT)

and

push

changes

Update

version

numbers

on

release

branch

(from

A.B.C-SNAPSHOT

to

A.B.C)

and

push changes

Update CHANGES

Update documentation

Build, Test and Push Changes

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.

Download the release candidate

Sanity Test

Sign

Verify Signatures

Tag Release Candidate

Stage

Community reviews the RC

Vote

Iterate based on feedback until vote passes

Once vote passes, tag the release:

Promote

Verify that the results are accessible.

Publish to Maven Repository

Preparation

Release

Wait 24 hours for release to propagate to mirrors.

Update site

Create version in JIRA for release X.Y.

Send announcements to the user and developer lists.

Update CHANGES with header for new changes

Remove old release from dist.apache.org