The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

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.

Release Procedure

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.

Admin Resources

Grab a copy of the admin resources:

git clone http://git-wip-us.apache.org/repos/asf/couchdb-admin.git

Any path in this document that references the "couchdb-admin" directory should be modified to point to this Git clone.

Some of these scripts take actions on your behalf, such accessing people.apache.org or checking files into Subversion.

Because of this, you must to read and understand the source code for every script that you use.

It would be prudent to examine the recent Git history before you start the release.

You are responsible for the actions these scripts take.

Timetable

We operate on a release timetable.

These are the actions to take each month:

The notice email can be found here:

couchdb-admin/email/notice_release.txt

The merge request email can be found here:

couchdb-admin/email/request_merge.txt

The VOTE and DISCUSS threads are covered by the rest of these instructions.

Once all this has been done, you must identify the type of release:

If this is a patch release, master should be merged into the appropriate release branch.

Otherwise, you should create a brand new release branch.

Preparing the Docs

Run through the following items by hand:

Build a list of CVE numbers:

./couchdb-admin/release/build_cve_list.sh 

This will produce output that ends with something like this:

Writing CVE numbers...
/tmp/build_cve_list.sh.9PhpoO/cve_list.txt

Check the documentation:

./couchdb-admin/release/check_docs.sh CVE_LIST_FILE

Replace CVE_LIST_FILE with the file generated by the build_cve_list.sh script.

So, in this instance, you would run:

./couchdb-admin/release/check_docs.sh /tmp/build_cve_list.sh.9PhpoO/cve_list.txt

This is going to check several things for you.

There will be a bit that look like:

Checking CVEs in changelog.rst...

It should be empty.

If you see any output here, it means a CVE is missing from the changelog.rst file.

You should expect to see output here for an undisclosed CVE.

There will be several sections that look like:

Comparing changelog.rst, 0.8.x to 0.9.x...

These sections should be empty.

If you see any output here, it means some entries in changelog.rst are missing in a later version.

Information in the changelog.rst should always be merged forward between branches.

There will be several sections that look like:

Scanning 0.8.x...

These sections should be empty.

Occasionally, you will see output that looks like:

# This version has not been released yet.

This is fine, and indicates that there are unreleased changes on the branch.

It must not appear on the branch you are about to release.

If this script generates any errors, you should fix them.

While working on the fix, you may find that you need to run the script repeatedly.

When it first runs, you will see something like this:

Creating temporary directory...
/tmp/check_docs.sh.9oNHt9

You can copy that directory name and append it the command to re-use the cached data:

./couchdb-admin/release/check_docs.sh CVE_LIST_FILE CACHE_DIR

Replace CVE_LIST_FILE with the file generated by the build_cve_list.sh script.

Replace TMP_DIR with the directory created by the previous invocation of the check_docs.sh script.

So, in this instance, you would run:

./couchdb-admin/release/check_docs.sh /tmp/build_cve_list.sh.9PhpoO/cve_list.txt /tmp/check_docs.sh.9oNHt9

This will be significantly faster than running the script from scratch again.

Preparing the Community

This section has been superseded by the Timetable section above.

This section will eventually include a step that requires you to check Travis.

Unfortunately, our continuous integration system needs some work before we can add this to the release procedure.

Generate a release proposal:

./couchdb-admin/email/discuss_release.sh CACHE_DIR BRANCH VERSION

Replace CACHE_DIR with the temporary directory name from the check_docs.sh script.

Replace BRANCH with the branch you are releasing from.

Replace VERSION with the version you are releasing.

So, in this instance, you might run:

./couchdb-admin/email/discuss_release.sh /tmp/check_docs.sh.9oNHt9 1.3.x 1.3.0

This will output something like:

Email text written to: /tmp/discuss_release.sh.FNISJ9/email.txt
Send the email to: dev@couchdb.apache.org
Files in: /tmp/discuss_release.sh.FNISJ9

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

Preparing the Candidate

If the proposal meets no objection, you can continue.

Build a release candidate:

./couchdb-admin/release/build_candidate.sh BRANCH VERSION

Replace BRANCH with the branch you are releasing from.

Replace VERSION with the version you are releasing.

So, in this instance, you might run:

./couchdb-admin/release/build_candidate.sh 1.3.x 1.3.0

This will do everything that is required to prepare the release candidate for you.

When the script is finished, you should see something like:

Check complete...
Files in: /tmp/build_candidate.sh.DOtlGR

The release candidate and the corresponding ish file can be found in this directory.

The ish file contains the tree-ish of the branch the release was taken from.

Using a Build Host

You may use a build host to prepare the release candidate.

Software like VirtualBox will allow you to provision virtual machines locally.

An infrastructure provider like Amazon Web Services will allow you to provision virtual machines remotely.

Both sorts of build host fine, as long as you're only running the build_candidate.sh script on them.

All other parts of this process must be done on your local machine.

Checking the Candidate

All of the standard checks are performed for you by the scripts.

However, assume that you cannot trust:

An attacker may have compromised either.

Accordingly, you should subject the release candidate to a number of your own tests.

Some ideas:

This part of the process is left to your discretion.

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

You may need to set the GPG_TTY first:

export GPG_TTY=`tty`

Publishing the Candidate

Once you are satisfied with the release candidate, you can sign it, publish it, and call a vote.

You can do all of these things at once by running:

./couchdb-admin/release/publish_candidate.sh CACHE_DIR BRANCH VERSION CANDIDATE

Replace CACHE_DIR with the output from the build_candidate.sh script.

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number.

So, in this instance, you might run:

./couchdb-admin/release/publish_candidate.sh /tmp/build_candidate.sh.DOtlGR 1.3.x 1.3.0 1

The candidate number should start at 1 and increase with each successive vote.

If the vote fails, and you're doing a second, you might run:

./couchdb-admin/release/publish_candidate.sh /tmp/build_candidate.sh.DOtlGR 1.3.x 1.3.0 2

If you attempt to publish a duplicate candidate number, you will get a cryptic Subversion error.

When the script has finished, it will output something like:

Email text written to: /tmp/publish_candidate.sh.KzG6bd/email.txt
Send the email to: dev@couchdb.apache.org
Files in: /tmp/publish_candidate.sh.KzG6bd

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values, or remove sections, as necessary.)

The vote is now underway.

Preparing the candidate is not the same as voting on it.

You should now follow the test procedure and vote on the candidate yourself.

After you've done that, open this file:

couchdb-admin/email/request_binaries.txt

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values as necessary.)

After this, you should send a tweet to publicize the RC (and get @CouchDB to retweet it):

Help wanted: CouchDB 1.6.0-rc.1 is ready for testing, please give it a whirl! <link to mailing list message>

Preparing the Binary Packages

Everyone is welcome to prepare binary packages for the release.

All binaries must be prepared from the release artefacts.

After voting on the release, you should prepare your binaries from the release artefacts you just voted on.

Create the directory in Subversion:

svn mkdir --parents \
https://dist.apache.org/repos/dist/dev/couchdb/binary/PLATFORM/VERSION/rc.CANDIDATE \
-m 'Add VERSION-rc.CANDIDATE PLATFORM dir'

Replace PLATFORM with the platform you built the binaries on.

Replace VERSION with the version you are building from.

Replace CANDIDATE with the candidate you are building from.

Check out this directory:

svn co https://dist.apache.org/repos/dist/dev/couchdb/binary/PLATFORM/VERSION/rc.CANDIDATE

Replace the variables in the URL as before.

Prepare the binary files and then move them into this directory.

Change into this directory, and add your files.

Then check in your files:

svn ci -m 'Add VERSION-rc.CANDIDATE PLATFORM files'

Go to https://dist.apache.org/repos/dist/dev/couchdb/binary/ and check that your changes are visible.

If you are not a committer, please submit your binaries to the list and request a review.

If a committer feels comfortable with your submission, they will move your binaries into Subversion.

It is the committer's individual responsibility to review your submission and determine that your binaries are suitable for distribution.

Once the binaries are available in Subversion, the committer who checked them in should post a note to the list.

The community should be invited to download and test the binaries before distribution.

Please note that binaries are never voted on. They are provided by individuals for the convenience of the community.

Preparing the Release Notes

Prepare the basic release notes now, and then request that people annotate as appropriate.

Create a temporary directory:

mkdir -p /tmp/couchdb

Create the release notes directory in Subversion:

svn mkdir --parents \
https://dist.apache.org/repos/dist/dev/couchdb/notes/VERSION/rc.CANDIDATE \
-m 'Add VERSION-rc.CANDIDATE release notes dir'

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number.

Check out the release notes directory:

svn co https://dist.apache.org/repos/dist/dev/couchdb/notes/VERSION/rc.CANDIDATE /tmp/couchdb/notes

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number.

Copy the template file:

cp ./couchdb-admin/notes/template.html /tmp/couchdb/notes/apache-couchdb-VERSION.html

Replace VERSION with the version you are releasing.

In this file, replace VERSION with the version you are releasing.

In this file, replace RELEASE with the type of release you are doing.

Go through the CHANGES file and copy each section and summary.

For each ticket referenced, add a link to the JIRA URL.

Change into the temporary directory:

cd /tmp/couchdb/notes

Add the release notes to Subversion.

Update the svn:mime-type property:

svn propset svn:mime-type text/html apache-couchdb-VERSION.html

Replace VERSION with the version you are releasing.

And commit your changes:

svn ci -m 'Add VERSION-rc.CANDIDATE release notes'

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number.

Open this file:

couchdb-admin/email/request_notes.txt

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values as necessary.)

Stop here. Come back to this point of the release notes instructions on release day.

In this file, replace ISH with the tree-ish of the tag you created.

In this file, replace DATE with the date of the release. This should take the form of YYYY-MM-DD.

Check Windows or OS X packages are not available, modify the line that say they are.

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

Change in to the temporary directory:

cd /tmp/couchdb/notes

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.

Add the text file to Subversion.

Commit both files:

svn ci -m "Update VERSION release notes"

Replace VERSION with the version you are releasing.

Now, publish the release notes:

svn cp \
https://dist.apache.org/repos/dist/dev/couchdb/notes/VERSION/rc.CANDIDATE \
https://dist.apache.org/repos/dist/release/couchdb/notes/VERSION \
-m "Copy VERSION release notes dir"

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number.

Wrapping Up the Vote

You need to wait a minimum of 72 hours.

A successful vote needs a majority approval and at least three +1 binding votes.

A binding vote is a vote cast by a member of the PMC.

Release may not be vetoed, but any -1 votes should be taken seriously.

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!

If the vote fails, go back to the Preparing the Candidate section, and increment the candidate number.

When the vote passes, open this file:

couchdb-admin/email/result_release.txt

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values as necessary.)

Making the Release

Tag the candidate:

./couchdb-admin/release/tag_candidate.sh VERSION CANDIDATE GPG_KEY

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate number that passed the vote.

Replace GPG_KEY with your GPG key.

The script will do some basic checks to make sure the values look sane.

When the script has finished, it will output something like:

Release dist directory: https://dist.apache.org/repos/dist/release/couchdb/source/1.3.0
Files in: /tmp/tag_candidate.sh.bbLyFI

If there are binary packages to publish, do so like this:

svn cp \
https://dist.apache.org/repos/dist/dev/couchdb/binary/PLATFORM/VERSION/rc.CANDIDATE \
https://dist.apache.org/repos/dist/release/couchdb/binary/PLATFORM/VERSION \
-m "Copy VERSION PLATFORM binary dir"

Replace PLATFORM with the platform you built the binaries on.

Replace VERSION with the version you are releasing.

Replace CANDIDATE with the candidate you are building from.

Choose a date for the release. Tuesdays mornings PST are better, because they get more press coverage.

Your date should take into consideration the 24 hour delay while you wait for the mirrors to update themselves after you have uploaded the release files.

Open this file:

couchdb-admin/email/schedule_release.txt

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values as necessary.)

Come back to these instructions on release day.

On release day, go back to the release notes section and complete the rest of the process.

Copy the HTML version of the release notes, and draft a blog post.

Specifically, you should:

Save this post as a draft. Then click the "Full Preview" button and make sure it looks okay.

You must now wait until all the release files have been synced to the public mirrors. The mirrors can take up to 24 hours to update, so it's usually best to wait a day. You should be sure that both the source download and the binary downloads are all working.

Announcing the Release

Wait for the scheduled release time before announcing the release. If there is no scheduled release time, you can simply wait until the mirrors are up-to-date.

Update http://couchdb.apache.org/ to point to the new files (checkout the repository from https://svn.apache.org/repos/asf/couchdb/site).

Update the wiki with the new release information.

Wait for all changes to be synced to the public site.

Publish the blog post.

Copy the text version of the release notes into an email.

Remove the title from the text, and replace it with:

Dear Community,

Remove any hard line wraps, including in the list of changes.

Sign the email with:

On behalf of the CouchDB PMC,

The subject should be:

[ANNOUNCE] Apache CouchDB VERSION released

Replace VERSION with the version you are releasing.

Then send to the following lists:

@@ Move most of this into a template email.

Promoting the Release

Twitter

Log in to the CouchDB Twitter account, and send a tweet using this template:

Apache CouchDB VERSION has been released. This is a RELEASE release. Download: http://couchdb.apache.org/ Release notes: BLOG_URL

Replace VERSION with the version you just released.

Replace RELEASE with the type of release you just made.

Replace BLOG_URL with the URL to the blog post you just published.

Hacker News

Post a new item to Hacker News.

Use the following title template:

Apache CouchDB VERSION Released

Replace VERSION with the version you just released.

Submit the URL of the blog post you just published.

Leave the description blank.

Reddit

Post a several new items to Reddit.

Use the following title template:

Apache CouchDB VERSION Released

Replace VERSION with the version you just released.

Submit the URL of the blog post you just published.

Submit a new item for each of the following subreddits:

Lobste.rs

If this is an important release, you might want to post it to https://lobste.rs/. Follow the same procedure as Hacker News.

Google+

Log in as the CouchDB page.

Post a new link to the blog post you just published to the CouchDB page and make it public.

Post a new link to the blog post you just published in the CouchDB Google+ community news category.

In both instances, try to summarise the important information, such as the type of release, and the most prominent changes in this release.

Be sure to +1 each post from your own account.

You should also consider sharing the post made by the CouchDB page publicly via your own account.

Facebook

Similar to Google+, post a link to the CouchDB page. Try to provide a useful summary of the release.

Be sure to like the post from your own account.

Mailing List

Open this file:

couchdb-admin/email/request_promotion.txt

Copy the text from that file into an email.

(You should replace values as necessary.)

Then send to the following lists:

Doing Housekeeping

Look at the list of current releases and update it.

Archive:

Archive these releases by calling a vote on the dev@ list, with your rationale.

@@ This bit is in the wrong section. Sort this out. This email is for notifying people about the release. We need an email that notifies people of the pending archive action.

Open this file:

couchdb-admin/email/schedule_release.txt

Copy the text from that file and send an email to the dev@couchdb.apache.org mailing list.

(You should replace values as necessary.)

Assuming this discussion reaches consensus, you should proceed to archive the release.

Remove the entry from the wiki.

@@ Do not run these commands, yet. Need to figure out a way to set up mod_rewrite redirects so that the old links still work for things like Homebrew. There was a JIRA set up for cleaning up our dist dir like this. Find details. For now, just remove the links from the wiki.

Run these commands:

svn rm \
https://dist.apache.org/repos/dist/release/couchdb/source/VERSION \
-m 'Remove Apache CouchDB VERSION'
svn rm \
https://dist.apache.org/repos/dist/release/couchdb/notes/VERSION \
-m 'Remove Apache CouchDB VERSION release notes'

Replace VERSION with the version you are archiving.

Then, for each platform, run:

svn rm \
https://dist.apache.org/repos/dist/release/couchdb/binary/PLATFORM/VERSION \
-m 'Remove Apache CouchDB VERSION PLATFORM binaries'

Replace VERSION with the version you are archiving.

Replace PLATFORM with the platform of the binaries you are archiving.

Do not worry about deleting these files. They will live on in the archives.

Troubleshooting

If you get an error about not being able to find pdflatex and you're running on OS X, first make sure that you have MacTeX installed. If you do, and you're still experiencing an error, it might be the case that MacTeX has failed to set up your PATH properly.

One workaround is to set your PATH manually:

PATH=$PATH":/usr/texbin" ./build_candidate.sh 1.3.x 1.3.0

Obviously, replace the arguments to build_candidate.sh as appropriate.

Useful Resources

Release_Procedure (last edited 2014-04-09 17:53:24 by NoahSlater)