We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

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.


A typical timeline might look like this:

Each one of these items is the responsibility of the Release Manager.

The developers submit merge requests for completed work to the Release Manager.

The Release Manager should follow this document when handling merge requests.

Nothing should be committed to a release branch besides what goes through this process.

If we all follow this, it will improve our code quality, test coverage, and documentation.

Feature Branches

Most work should happen in feature branches.

If there is not already a ticket for your work, pleasecreate one.


Please use the ticket number, the type of the branch, along with a very short descriptive phrase, for your branch name.

If the ticket was COUCHDB-1234, and the ticket title was My Cool Feature, your branch should be called 1234-feature-cool. If the issue is a bug and the branch includes the bug fix, it should be called 1234-fix-cool. If cool are multiple words, separate them with a dash: 1234-feature-cool-stuff.

Git Best Practice

Developers are free to use a feature branch in any way they see fit during development. Prior to submitting a merge request to dev@, though, the branch should be prepared according to the following rules, as the commits on the feature branch will be a permanent part of the couchdb project's history.

A feature branch should consist of the smallest number of meaningful commits as possible. For bug fixes and small features, this is likely to be a single commit. For larger changes, multiple commits might be necessary. The guiding principle for deciding how many commits is coherence. A commit should be readable and, ideally, implement one distinct idea. A feature that requires multiple enhancements to achieve its goal should be presented as multiple commits. It is *not* necessary for the system to pass the test suite for any subset of these commits, only their combination.

Merge Request

The merge request is done by the developer wanting to add changes to a release branch.

If you want to make a merge request, please follow these steps:

Merge Testing

If someone has posted a merge request to the mailing list, you should test it.

Here are some things you can do:

Please look in to as much of this as possible, then send your results back to the list.

Hopefully, we can automate some of this testing at some point soon.

Do you fancy helping us with that? Get in touch!


An actual merge should only be done by the active Release Manager.

Once a merge request has been tested by the community, and you are happy, you can proceed.


Follow these instructions to merge a feature in to one release branch.

Feature branches are merged to release branches using 'git merge --no-ff <FEATURE BRANCH>'. This guarantees a merge commit, which are the only kinds of commit that will appear on release branches. If the merge results in conflicts, the release manager rejects the merge commit with an reply to the dev@ thread. If the merge is successful, the release manager should run 'make distcheck' and push the merge upstream if the tests pass.


Follow these instructions to merge a bugfix in to multiple release branches.

For each release branch, 'git checkout <RELEASE BRANCH>' and 'git merge --no-ff <BUGFIX BRANCH>'. If any of the merges fail, the merge request is rejected.


Follow these instructions to generate a patch for unsupported releases.

(Security fixes can be merged in to supported release branches just like bugfixes.)

Merge_Procedure (last edited 2013-07-21 08:39:48 by 178)