You need to be added as a contributor 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. |
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.
Step 1 of any release process is: every time you go through the release process, update this wiki page to reflect any changes you make! Do this every release, so nothing gets out of date.
You may want to 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. Many have not yet been updated for the 2.x series of releases. At the moment, the release team is not using the admin repo scripts at all.
Before starting the release process for CouchDB, the following sanity checks should be made:
Ensure you are running the lowest support version of Erlang locally. If you run with too new a version of Erlang, you may end up building a release asset that is unbuildable on older Erlang VMs (because the shipped rebar
binary will be incompatible).
Checkout the code locally and run a clean build and test:
# If you don't have CouchDB downloaded yet: $ git clone https://github.com/apache/couchdb && cd couchdb # # or, if you already have CouchDB cloned: $ cd couchdb && git pull && git checkout master && git reset --hard && git clean -ffdx # # Then: $ ./configure && make check |
rebar.config.script
file.version.mk
and rel/reltool.config
.If possible, check that the automated packages are valid. Check the last full CI run in jenkins or build them yourself on a Linux machine with Docker installed:
$ git clone https://github.com/apache/couchdb-pkg $ git clone https://github.com/apache/couchdb && cd couchdb && ./configure --without-proper && make dist $ cd ../couchdb-pkg $ ./make-releases.sh ../couchdb/apache-couchdb-*.tar.gz |
Meanwhile, make the following updates to the documentation:
Update the README.rst
file with important information.
Update the README-DEV.rst
file with important information.
In the couchdb-documentation
repository, update the src/whatsnew/X.X.rst
file with important information.
Compile a list of bugs fixed and improvements that have been fixed in this release.
See src/whatsnew/2.2.rst
for an example.
This can be done with a GitHub search of the form: https://github.com/apache/couchdb/compare/2.1.0...master
From the command line, the following approach works well:git show-branch --sha1-name master X.X.X | more
For each remaining commit on master:
Now do the same thing as above, but for documentation and fauxton. Pull out only
the big-ticket items.
master
branch for any changes that won't make this release. These may be candidates for Known Issues in the documentation.Add a breaking changes section to this file if necessary.
Ensure that any new CVEs identified are summarized in the documentation. CVEs are described in files under couchdb-documentation/src/cve/*.rst
.
Generate a release proposal from the discussion release template. Edit as appropriate. Send it to the dev@couchdb.apache.org mailing list.
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 from Apache resources. It is generally better if your key is also signed by other people, especially by members of the CouchDB PMC.
Your public key must be added to: http://www.apache.org/dist/couchdb/KEYS
You should also upload your key to a public key server for good measure.
Make sure your key is registered to gpg:
gpg --list-keys |
You may need to set the GPG_TTY first:
export GPG_TTY=`tty` |
If your signing key is not the default, add the --default-key=<hash>
option to the gpg signing command(s) below. You can change the default in your gpg.conf file with the default-key
directive.
If the proposal meets no objection, you can continue:
rebar.config.script
file and look at all of the dependency version numbers. If any are raw git hashes (not x.x.x-style version numbers), tag those sub-repositories first. Then, update the rebar.config.script
with these version numbers and commit the change. No dependencies should be referenced by a raw git hash.make check
as in the first section of this process, being sure to run the git clean
and git reset
commands. If this is the first RC for a new major or minor release (3.0.0, 2.3.0, etc. but not 2.3.1) then create a branch:
$ git checkout -b #.#.x git push origin |
Tag this version with x.x.x-RC#
where # represents which release candidate this is (1, 2, 3...):
$ git tag -a x.x.x-RC# -m "Version x.x.x-RC#" --sign $ git push origin x.x.x-RC# |
Build the release candidate tarball (substitute the correct number for the #
below):
$ cd couchdb $ git reset --hard && git clean -ffdx $ ./configure --without-proper $ make dist |
This wiki has separate instructions on testing a release candidate.
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.
Once you are satisfied with the release candidate, you must sign it, publish it, and call the vote.
Sign the release and generate the appropriate checksum files:
$ gpg -b --armor apache-couchdb-x.x.x-RC#.tar.gz $ sha256sum apache-couchdb-x.x.x-RC#.tar.gz > apache-couchdb-x.x.x-RC#.tar.gz.sha256 # If on Windows, fix the line endings in the checksum files! |
Add the files to the official Apache distribution site:
$ svn co https://dist.apache.org/repos/dist/dev/couchdb/source $ mkdir -p source/x.x.x/rc.# $ cp apache-couchdb-x.x.x-RC#.tar.gz* source/x.x.x/rc.# # # if this is the first RC for a new release: $ svn add source/x.x.x # otherwise: $ svn add source/x.x.x/rc.# $ svn propset svn:mime-type text/plain source/x.x.x/rc.#/*.gz.asc source/x.x.x/rc.#/*.gz.sha* # # Add a meaningful comment, like "Adding CouchDB x.x.x-RC1 to dev tree" $ svn ci -m "Adding CouchDB x.x.x-RC# to dev tree" |
Publishing the candidate is not the same as voting on it. You should now follow the test procedure and vote on the candidate yourself. |
Note: As of 3.1.0, we're not doing Apache binary packages for macOS or Windows. Neighbourhoodie have taken over this work.
Everyone is welcome to prepare binary packages for the release. Binary packages are never required for release candidates. All binaries must be prepared from the release artifacts. After voting on the release, you should prepare your binaries from the release artifacts you just voted on. If you can't build these yourself, ask for help on IRC or the mailing list.
Create the directory in Subversion:
svn mkdir --parents \ https://dist.apache.org/repos/dist/dev/couchdb/binary/{mac|win}/x.x.x/rc.# \ -m 'Add x.x.x-rc.# {mac|win} dir' |
Check out this directory:
svn co https://dist.apache.org/repos/dist/dev/couchdb/binary/PLATFORM/VERSION/rc.CANDIDATE |
Add your files to this directory, then check in your files:
svn ci -m 'Add x.x.x-rc.# {mac|win} 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.
If you have shell access to couchdb-vm2.apache.org
, you can capture the latest auto-built Debian/Ubuntu/RHEL/CentOS package repositories from Jenkins and move it aside to a x.x.x-RC# directory for testing. The repos all live under the /var/www/html
path.
Binaries are never voted on. They are provided by individuals for the convenience of the community. |
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. Releases 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, download and customize the release_3_result.txt announcement template from the couchdb-admin repo. Then, send it to the dev@couchdb.apache.org mailing list.
If the release was approved by formal vote, you can proceed to make the release happen.
Tag the candidate with the x.x.x version number:
$ cd couchdb && git checkout x.x.x-RC# $ git tag -a x.x.x -m "Version x.x.x" --sign $ git push origin x.x.x |
The release tarball can now be renamed:
$ cp apache-couchdb-x.x.x-RC##.tar.gz apache-couchdb-x.x.x.tar.gz $ cp apache-couchdb-x.x.x-RC##.tar.gz.asc apache-couchdb-x.x.x.tar.gz.asc $ cp apache-couchdb-x.x.x-RC##.tar.gz.sha256 apache-couchdb-x.x.x.tar.gz.sha256 |
Push the files to the Apache distribution Subversion tree:
$ svn mkdir --parents \ https://dist.apache.org/repos/dist/release/couchdb/source/x.x.x \ -m 'Add CouchDB x.x.x dir' $ svn co https://dist.apache.org/repos/dist/release/couchdb/source/x.x.x $ cp apache-couchdb-x.x.x.tar.gz* x.x.x/ $ cd x.x.x && svn add . && svn ci -m 'Add CouchDB x.x.x release files' |
While you're at it, clean up the dist/release/couchdb directory:
The process is simple. Run these commands, once for each version and platform combination:
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/binary/PLATFORM/VERSION \ -m 'Remove Apache CouchDB $VERSION $PLATFORM binaries' |
Do not worry about deleting these files. They will live on in the archives.
Note: As of 3.1.0, we're not doing Apache binary packages for macOS or Windows. Neighbourhoodie have taken over this work.
The macOS and Windows binaries should be uploaded to the official https://dist.apache.org/repos/dist/release/couchdb/binary tree, using instructions similar to the above.
However, because it provides better visibility into our downloads (and is linked directly from our website), these should also be uploaded to Bintray. You will need a Bintray account to do this, and have access to https://bintray.com/apache/couchdb/ granted via INFRA before you can upload.
/win/X.X.X
or /mac/X.X.X
as appropriate.First, build the binaries. On a Linux machine with Docker:
$ docker pull --all-tags couchdbdev $ git clone https://github.com/apache/couchdb-pkg && cd couchdb-pkg $ ./build.sh couch-all https://dist.apache.org/repos/dist/release/couchdb/source/#.#.#/apache-couchdb-#.#.#.tar.gz |
pkgs
directory include the expected results:couch/centos-6/x86_64
should contain the couchdb RPM as well as the SpiderMonkey 1.8.5 RPMs.couch/centos-7/x86_64
should contain the couchdb RPM.couch/debian-jessie|debian-stretch|ubuntu-trusty|ubuntu-xenial
|ubuntu-bionic
should each contain the appropriate couchdb deb
.Now, upload the binaries to Bintray and publish them:
$ BINTRAY_USER="your-userid-here" BINTRAY_API_KEY="your-key-here" ./build.sh couch-upload-all |
If this fails, or you want to do it the old labour intensive way, the old web-based approach is below:
/el6/x86_64
or /el7/x86_64
as appropriate.$ curl -X POST -u $BINTRAY-USER:$BINTRAY-API-KEY https://api.bintray.com/gpg/apache/couchdb-deb/CouchDB/versions/X.X. |
master
.apache/couchdb:X.X.X
using docker push
. It's also recommended to push the image as apache/couchdb:#.#, apache/couchdb:# and apache/couchdb:latest. Do not do the last 2 if this is just a maintenance release on an older supported branch.master
. Make any changes as requested by the Docker team.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.
Use the contents of couchdb-admin/email/schedule_release.txt
file to schedule the release, and send the email to the dev@couchdb.apache.org mailing list.
While waiting for the actual announcement to occur, the following preparations can take place:
marketing@couchdb.apache.org
mailing list.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.
Then:
asf-site
.)couchdb-admin/email/announce_release.txt
template. You will want to cut and paste the release notes from the website into this email and prepare appropriately.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 |
Post a new item to Hacker News.
Use the following title template: Apache CouchDB VERSION Released
Submit the URL of the blog post you just published.
Post several new items to Reddit.
Use the following title template: Apache CouchDB VERSION Released
Submit the URL of the blog post you just published.
Submit a new item for each of the following subreddits:
If this is an important release, you might want to post it to https://lobste.rs/. Follow the same procedure as Hacker News.
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.
Open the couchdb-admin/email/request_promotion.txt
template and edit as necessary. Then, send to the following lists:
Apache Release Policy - the official ASF stance to which we must match
Apache Release Publishing - the technical steps necessary to publish a release
Apache Release Distribution Policy - where the releases go, how to link to them and how to announce them.
Apache's How to OpenPGP - for setting up OpenPGP
Verifying ASF Releases - how to check a signature once it's been made