You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Making a Source Release

Any Apache CouchDB committer is free to make a source release, but they are usually made by the release team.

If you'd like to help out with making a release, lets us know on the couchdb-dev mailing list.

Contents

  1. Making a Source Release
  2. Checklist
  3. Preparing the Community
  4. Preparing the Release
  5. Release Signing
  6. Creating the Release Artefacts
  7. Checking the Release Contents
  8. Calling a Vote
  9. Preparing the Release Notes
  10. Making the Release
  11. Doing Housekeeping
  12. Useful Resources

Checklist

Preparing the Community

Call a vote on the couchdb-dev mailing list asking for a request for comments on the release. Ask all developers to specifically check the NEWS and CHANGES file for anything that has been added in this release.

Preparing the Release

First make sure your local repository has everything from the public repository: 

git fetch origin

Find a list of branches: 

git branch -a

Checkout the branch you're releasing from: 

git checkout -b Y.Y.x origin/Y.Y.x

You should make sure your branch matches whats on the remote repository. First check that you don't have any work that you're willing to lose: 

git status

When you have your work saved, forcefully update your branch to the version in the remote repository: 

git reset --hard HEAD
git clean -qfxd
git rebase origin/Y.Y.x

Grab the current tree-ish: 

git show HEAD | head -n 1 | cut -d " " -f 2

It is generally a good idea to work under a clean temporary directory.

You can then run the following commands: 

git archive --prefix=Y.Y.Y/ -o Y.Y.Y.tar <tree-ish>
tar -xf Y.Y.Y.tar

You must then use the Y.Y.Y directory to prepare the release: 

cd Y.Y.Y

Release Signing

You will need a GPG key pair to sign the release.

If you do not have one already, see the Useful Resources section for more help.

It is generally better if your key is also signed by other people.

Your public key must be added to:

You should also upload your key to a public key server for good measure.

The build system will invoke GnuPG in a way that defaults to your first secret key.

If this is not the key you wish to sign the release with, run this command: 

export GPG_ARGS="--default-key=DEADBEAF"

Replace DEADBEAF with your key ID, which you can find by running: 

gpg --list-keys

Creating the Release Artefacts

To build the source for distribution you should then run the following command: 

./bootstrap && ./configure && make distsign

If everything was successful you should see the following files in the working directory ready for distribution:

Checking the Release Contents

Remove any existing temporary directory: 

rm -rf /tmp/couchdb

Obviously, don't run this command if you're already using this directory for something else.

The location isn't important, but this is a sensible default.

Create a new temporary directory to work in: 

mkdir /tmp/couchdb

You can safely remove this directory and all of its contents when you're done.

Move the release files to the temporary directory: 

mv apache-couchdb* /tmp/couchdb

Move the source tarball to the temporary directory: 

mv ../Y.Y.Y.tar /tmp/couchdb

Change to the temporary directory: 

cd /tmp/couchdb

Unpack the release tarball: 

tar -xvzf apache-couchdb-Y.Y.Y.tar.gz

Then unpack another copy of the source tarball: 

tar -xvf Y.Y.Y.tar

Then compare the tarball with the source directory: 

diff -r apache-couchdb-Y.Y.Y Y.Y.Y

Use your judgment here to figure out if anything is missing, or has been included by mistake.

Upload the release files to your public_html directory on people.apache.org and make sure they are world readable.

Do not upload the exported tag directory, of course. That was only for testing.

Calling a Vote

Before you call the vote, you should now download your own release artefacts and run the test procedure with them.

Update the test procedure to use the correct values so that copying and pasting the commands will work.

If they pass your own tests:

The vote email must include the full tree-ish used to prepare the release.

The release manager has the power to abort a vote at any point and for any reason.

Please try to make it a good one though!

A vote can only pass if there are at least three +1 votes. These votes can come from anyone, including non-committers, and in fact, everyone is encouraged to partake in and vote on each release. However, it is preferable that at least three +1 votes come from the committers, or better yet, the PMC. Once three +1 votes have been counted, the vote can pass. However, if anyone votes -1 or expresses any serious concern, that should be addressed. Usually, this will be cause to abort the vote. A vote can only be closed after three working days. This allows most people a chance to test and vote on the release.

Preparing the Release Notes

Go through the NEWS file and expand each bullet point as appropriate.

Format this document as HTML, and call it something like: 

apache-couchdb-Y.Y.Y.html

Check that this HTML looks good when used for a draft blog post.

Then generate a text only version by running: 

elinks -dump -no-numbering -no-references apache-couchdb-Y.Y.Y.html > apache-couchdb-Y.Y.Y.txt

Check the text only version to make sure that any important links are not lost.

For example, a JIRA ticket that is not referenced by number.

Upload these files to /www/www.apache.org/dist/couchdb/notes/Y.Y.Y on people.apache.org.

Making the Release

Create a signed tag: 

git tag -u DEADBEAF Y.Y.Y <tree-ish>

Use a tag message like this: 

CouchDB Y.Y.Y

Vote results: <URL>

Use the Apache URL shortener to produce the URL:

The URL should point to the vote results email you previously sent.

Now, push the tag: 

git push origin Y.Y.Y

Now, follow these steps:

At each stage of the actual release, it is expected that a person can follow the trail of changes back to the source. Because most of these systems are slow, things must be done in the correct order. It would be unfortunate if the website listed a release that was not available on a local mirror, or that was missing a corresponding tag in the Git repository. The changes should always propagate from the source, to the dist directory, to the mirrors, to downloads.html, and finally to the actual release announcement.

Doing Housekeeping

Useful Resources

Release_Procedure (last edited 2012-05-07 22:09:13 by NoahSlater)