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.
...
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 |
---|
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}
|
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://gitbox |
Keys
Prepare
Update version numbers
(from X.Y.Z-SNAPSHOT to X.Y.Z)
Update CHANGES
Update CHANGES.txt with release date (Release X.Y - MM/dd/yyyy) and (if needed) add additional changelog entries
Update documentation
Commit updates
Build
Make a clean checkout
...
.apache.org/repos/asf/ |
...
Build it.
Run unit tests
...
knox.git knox-{X.Y.Z}
cd knox-{X.Y.Z}
|
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 |
---|
git pull
git commit --all --message "Updating branch."
ant verify
git push
|
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.
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-${KNOX_VERSION}-src.zip.asc knox-${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 |
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}
cat knox-${KNOX_VERSION}-src.zip.sha256 && openssl sha256 knox-${KNOX_VERSION}-src.zip
cat knox-${KNOX_VERSION}-src.zip.sha512 && openssl sha512 knox-${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 sha512 knoxshell-${KNOX_VERSION}.zip
cat knoxshell-${KNOX_VERSION}.tar.gz.sha256 && openssl sha256 knoxshell-${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-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 ..
ant stage-candidate
|
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{X.Y.Z}-release --message "Release of v{X.Y.Z}"
git push origin --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
The Apache Knox Gateway is currently distributed as a single Zip file. Following the steps described below this Zip file will be created in the target directory. The following process can be used create a release build without an existing repository clone.
Code Block |
---|
git clone https://git-wip-us.apache.org/repos/asf/incubator-knox.git knox
cd knox
ant release
|
If the repository has already been cloned the following process should be used.
Code Block |
---|
git pull
ant release
|
Branch
Create a branch for release maintenance
Sign
Stage - Step-By-Step Guide to Mirroring Releases.
e.g., gpg --armor --output tika-X.Y.tar.gz.asc --detach-sig tika-X.Y.tar.gz \
md5sum tika-X.Y.tar.gz > tika-X.Y.tar.gz.md5
Vote
13. Release Review and Vote: Use the following email as a template for a real email sent to the private@lucene.apache.org and the tika-dev@lucene.apache.org lists, calling for a vote on the release candidate (posted on a publicly accessible website):
Iterate based on feedback until bote passes
Publish
15. Once vote passes, tag the tika release:
svn copy https://svn.apache.org/repos/asf/lucene/tika/trunk \ https://svn.apache.org/repos/asf/lucene/tika/tika/tags/X.Y
-m "Tika X.Y release."
16. Copy release tar file to people.apache.org:/www/www.apache.org/dist/lucene/tika. based on vote (also included *.asc file and *.md5 file)
...
Wait 24 hours for release to propagate to mirrors.
Update site
4. 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/asf/lucene/site/. The second change may require additional rights News.
Create version in JIRA for release X.Y.
Send announcements to the user and developer lists.
...
Update CHANGES with header for new
...
Update version numbers for to A.B-dev (assuming A.B is next release number) in:
pom.xml - version tag
2. Update CHANGES with header for new changes
3. Create version in JIRA for development snapshots (X.Y.Z)
...
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 | ||||
---|---|---|---|---|
|
...