Testing a Source Release

Any Apache CouchDB user is free to test a source release, and in fact we encourage you to do so!

This might seem like a complex process, but that is only because it has been documented very thoroughly to make sure that we're all doing the same thing. Once you've done this a few times, the whole process becomes very easy to remember.

Setting Up

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.

Downloading the Release Artefacts

You should have a copy of the vote email with links to the committer's dist directory.

It will look a bit like this:

Obviously, the 1.2.0 bit will change between releases.

In this directory, you will find four files that look like this:

You should now create a another temporary directory: 

mkdir /tmp/couchdb/dist

Change into it: 

cd /tmp/couchdb/dist

And then download these files: 

wget http://people.apache.org/~nslater/dist/1.2.0/apache-couchdb-1.2.0.tar.gz
wget http://people.apache.org/~nslater/dist/1.2.0/apache-couchdb-1.2.0.tar.gz.asc
wget http://people.apache.org/~nslater/dist/1.2.0/apache-couchdb-1.2.0.tar.gz.md5
wget http://people.apache.org/~nslater/dist/1.2.0/apache-couchdb-1.2.0.tar.gz.sha

If you don't have wget installed, you can use curl -O which should do the same thing.

Verifying the Release Artefacts

All release managers should have their keys in this file:

You will need to import the keys into your local keychain before you can continue.

You can do this manually, from the KEYS file.

Or, you can import them from a public key server: 

gpg --recv-keys 61D50B88 43ECCEE1 DF3CEBA3 04F4EE9B

Once that is done, you can verify the release signature: 

gpg --verify apache-couchdb-*.tar.gz.asc

Check for:

If anything at all about this output look strange to you, please do flag it up on the mailing list.

You must then check the MD5 checksum of the release: 

md5sum --check apache-couchdb-*.tar.gz.md5

Check for an "OK" message.

You must then check the SHA checksum of the release: 

sha1sum --check apache-couchdb-*.tar.gz.sha

Check for an "OK" message.

Checking the Release Artefacts

SKIP THIS SECTION IF YOU DON'T KNOW ANYTHING ABOUT AUTOTOOLS

You should have a copy of the vote email with the git tree-ish used to build the release.

It will look a bit like this:

Obviously, the value will change between releases.

Create two new temporary directories: 

mkdir /tmp/couchdb/git
mkdir /tmp/couchdb/tree

Make a pristine copy from the tree-ish. 

git clone https://git-wip-us.apache.org/repos/asf/couchdb.git /tmp/couchdb/git
cd /tmp/couchdb/git
git archive --prefix=/tmp/couchdb/tree/ <tree-ish> | tar Pxf -

Change into your dist directory: 

cd /tmp/couchdb/dist

Unpack the tarball: 

tar -xvzf apache-couchdb-*.tar.gz

Compare the contents of the tarball to the release tag: 

diff -r apache-couchdb-1.2.0 ../tree

Lines starting with "Only in ../tree" should be part of bootstrap mechanism or source control configuration.

Lines starting with "Only in apache-couchdb-1.2.0" should be files produced by the bootstrap mechanism.

Nothing else should ever appear in this output.

If you have no idea what any of this means, you probably should have skipped this section!

Sample healthy output: 

Only in ../tree: .gitignore
Only in apache-couchdb-1.2.0: INSTALL
Only in apache-couchdb-1.2.0: Makefile.in
Only in apache-couchdb-1.2.0: acinclude.m4
Only in ../tree: acinclude.m4.in
Only in apache-couchdb-1.2.0: aclocal.m4
Only in apache-couchdb-1.2.0/bin: Makefile.in
Only in ../tree: bootstrap
Only in apache-couchdb-1.2.0: build-aux
Only in apache-couchdb-1.2.0: config.h.in
Only in apache-couchdb-1.2.0: configure
Only in apache-couchdb-1.2.0/etc: Makefile.in
[...]
Only in apache-couchdb-1.2.0/etc/windows: Makefile.in
Only in apache-couchdb-1.2.0/m4: ac_check_curl.m4
Only in ../tree/m4: ac_check_curl.m4.gz
Only in apache-couchdb-1.2.0/m4: ac_check_icu.m4
Only in ../tree/m4: ac_check_icu.m4.gz
Only in apache-couchdb-1.2.0/m4: libtool.m4
[...]
Only in apache-couchdb-1.2.0/m4: lt~obsolete.m4
Only in apache-couchdb-1.2.0/share: Makefile.in
[...]
Only in apache-couchdb-1.2.0/var: Makefile.in

Checking the Release Artefacts

Change into your dist directory: 

cd /tmp/couchdb/dist

Unpack the tarball: 

tar -xvzf apache-couchdb-*.tar.gz

Obviously, skip this step if you've already unpacked the tarball.

Change into the tarball directory: 

cd apache-couchdb-1.2.0

Configure CouchDB to install into your temporary directory: 

./configure --prefix=/tmp/couchdb/install

Run the unit tests: 

make check

If a test fails, you can run it again: 

$ ./test/etap/run test/etap/060-kt-merging.t

Where 060-kt-merging is the name of the specific test you want to run.

Install CouchDB into your temporary directory: 

make install

Start CouchDB: 

/tmp/couchdb/install/bin/couchdb

If you get the following error: 

Apache CouchDB 1.2.0 (LogLevel=info) is starting.
Failure to start Mochiweb: eaddrinuse

You already have a CouchDB server listening on the default port.

Edit your local.ini file: 

$EDITOR /tmp/couchdb/install/etc/couchdb/local.ini

Look for this: 

[httpd]
;port = 5984

And change it to this: 

[httpd]
port = 5985

Restart CouchDB.

CouchDB should now be running and listening for connections.

Open Firefox.

View the "About" screen in Firefox.

This should automatically update you to the newest version.

Put Firefox in to private browsing mode.

Visit:

If you had to change the port number in the previous step, you MUST update it to match in the URL above.

Please note that the unit tests do not run properly under Safari.

If you report problems with Safari, you will be asked to test again using Firefox.

Click on "Run All" and wait a few minutes.

Your browser will lock up while the tests are run.

Wrapping it Up

If you manage to get all the way through this without a single error, the release is good. Please reply to the vote email with a summary of the steps you completed. If anything strange happens, or you run into any problems, please reply to the vote email with an outline of the steps you took, and the problems you noticed. In some cases, it might be due to a slight difference in test setup. If that is the case, please update this document to help future testers.

Test_procedure (last edited 2012-03-28 21:52:42 by NoahSlater)