CouchDB Bylaws

This document was officially adopted by the CouchDB PMC as of 31 July 2014.

A full changelog is available on GitHub.

Table of Contents

1. Introduction

This document defines the bylaws under which the Apache CouchDB project operates. It defines the roles and responsibilities within the project, who may vote, how voting works, how conflicts are resolved, and voting rules for specific decision types.

This document is written for anyone who wishes to participate in the project. If this is your first time through this document, read this introduction, then read all the bolded text for a summary of the bylaws. Then, as you need more detail, read past the bolded text for an expanded explanation.

CouchDB is a project of the Apache Software Foundation (ASF). Apache CouchDB, CouchDB, and the CouchDB logo are trademarks of the ASF. The project resources are licensed to the public under the Apache License 2.0. Releases are made in the form of official signed source code archives. The ASF FAQ explains the operation and background of the Foundation.

CouchDB operates under a set of common principles known collectively as the Apache Way:

We value the community more than the code. A strong and healthy community should be a fun and rewarding place for everyone involved. Code, and everything else that goes with that code, will be produced by a healthy community over time.

The direction of the project and the decisions we make are up to you. If you are participating on the mailing lists you have the right to make decisions. All decisions about the project are taken on the mailing lists. There are no lead developers, nor is there any one person in charge.

Anyone can subscribe to the public mailing lists, and in fact, you are encouraged to do so. The development mailing list is not just for developers, for instance. It is for anyone who is interested in the development of the project. Everybody's voice is welcome.

Finally, use of these bylaws to enforce the letter of any rule and not its spirit (also known as "rule lawyering") is not acceptable behaviour.

2. Roles and Responsibilities

The ASF defines a set of roles with associated rights and responsibilities. These roles govern what tasks an individual may perform within the project. The roles are defined in the following sections.

Your role is bestowed on you by your peers in recognition of your past contributions to the project and your position of trust within the community. It is not tied to your job, your current employer, or your current activity level. We are interested in you as an individual and we understand that your interactions with the project may change over time.

Roles are never rescinded because of inactivity, unless that inactivity is causing a problem for the project. Fortunately, our decision making process means that inactivity is very rarely a problem. Roles will be rescinded if the Project Management Committee (or PMC, see 2.4. below) believes the individual is no longer able to responsibly discharge the duty of the role.

We understand that you have many roles in life. We use a hat metaphor to talk about these roles. For instance, you might have your work hat as well as several ASF hats. We expect you to know when to wear the appropriate hat, and to comport yourself in a manner befitting the interests of the Foundation when interacting with the project. Failure to do this is a serious dereliction of duty.

Sometimes it is a good idea to tell people which hat you are wearing. For instance, the PMC Chair might start an informal email by stating they are not wearing the PMC Chair's hat, just to be clear about how the statements ought to be interpreted.

We expect you to act in good faith. This is very important for a community that depends so heavily on trust.

2.1. Users

The most important participants in the project are people who use our software.

Users can participate by talking about the project, providing feedback, and helping others. This can be done at the ASF or elsewhere, and includes being active on the user mailing list, third-party support forums, blogs, and social media. Users who participate in this way automatically become contributors.

2.2. Contributors

A contributor is someone who makes contributions to the community, project, documentation, or code.

There is no special requirement to become a contributor. If you have a great idea for the project, you can get to work immediately. There is no need to ask permission. Most things can be accomplished by contributors with no special privileges or status on the project. Assistance can be provided if you need access to project resources to get your work done.

A contributor who makes sustained contributions to the project may be invited to become a committer.

2.3. Committers

A committer is someone who is committed to the project. In return for their commitment, they are given a binding vote in certain project decisions. Committers are hence responsible for the ongoing health of the project and the community.

We recognise commitment in many different areas. These include, but are not limited to:

More details are available in the contributor guide. If any of these things sound interesting to you, we welcome your help.

The role of committer is mandated at the Foundation level. Unfortunately, the usual definition of that word—being someone who commits code—can mean that non-coders are never given binding votes on a project. We think that's a problem. Contributions come in many shapes and sizes. Indeed, many of those non-code contributions are what the project needs the most.

To make this clear, we have chosen to define a committer as someone who is committed. We mean this in the sense of being loyal to the project and its interests. It is a position of trust, not an expectation of activity level. Anyone who is supportive of the community and the project will be considered as a candidate for being a committer.

As a matter of convenience, committers are also given write access to all of the public project infrastructure, including source control repositories, website, issue tracker, wiki, and blog. Access to social media accounts, and other third-party services, will be granted upon request.

All committers are required to have a signed Individual Contributor License Agreement (ICLA) on file. There is an ASF FAQ which provides more details about the requirements at the Foundation level.

Committers are expected to work cooperatively and to have good social skills. This is more important than any other sort of skill. Our committers make up the bulk of our active community, and as such, we rely on them to help us build and maintain that community.

A committer who makes a sustained contribution to the project may be invited to become a Project Management Committee (PMC) member.

2.4. Project Management Committee

The Project Management Committee (PMC) is responsible for the management of the project.

At the most basic level, the role of the PMC is oversight. The PMC must ensure that all relevant bylaws , policies, and procedures are adhered to. These exist at the Foundation-level and the project-level. See the project affairs page for more information.

Beyond this requirement, the primary goal of the PMC is to invest in the long term wellbeing of the community. For this reason, one of the most basic tasks of the PMC is the recruitment and management of project contributors. We believe that the size, diversity, and health of the community is essential for the quality, stability, and robustness of project and its social structures.

Activities of the PMC include, but are not limited to:

PMC members are held to a much higher standard than regular community members. This includes strict hat wearing, equitable decision making, and exemplary conduct. People look to PMC members for cues about how to behave. It is important that all PMC members understand the responsibility that they bear, and that they are individually committed to improving themselves and the project.

While security issues and release management are the responsibility of the PMC, the PMC typically delegates this to committers.

2.5. Chair

The project Chair is a PMC member responsible for Foundation level administrative tasks. It is not a technical leadership position, meaning the Chair has no special say in ordinary project decisions. But we do think of it as a cultural leadership position. Accordingly, position on cultural issues is something to consider when electing a Chair.

The Chair is elected by the PMC but appointed by the ASF Board via a Board resolution. The Chair is an officer of the Apache Software Foundation (with an official title of Vice President, Apache CouchDB) and has primary responsibility to the Board for the management of the project. The Chair is the eyes and ears of the Board, and reports quarterly on developments within the project.

The chair has primary responsibility to the Board, and has the power to establish rules and procedures for the day to day management of the communities for which the PMC is responsible, including the composition of the PMC itself.

Remember that, as in any meeting, the Chair is a facilitator and their role within the PMC is to ensure that everyone has a chance to be heard and to enable meetings to flow smoothly.

If the current Chair resigns, or the term of the Chair expires, the PMC will hold a Chair election.

The Chair has a 12 month term. The intention of this term is to allow for a rotation of the role amongst the PMC members. This does not prohibit the PMC from selecting the same Chair to serve consecutive terms.

2.6. Board of Directors

The Chair is responsible for the project to the Board of Directors (the Board) of the ASF. The Board is the nine-person legal governing body of the ASF, elected by the members of the Foundation. The Board provides the oversight of the Foundation's activities and operation, and has the responsibility of applying and enforcing the ASF's bylaws.

3. Decision Making

This section explains our approach to decision making and the formal structures we have in place to make this as easy as possible.

In descending order of preference, we prefer that decisions are made via:

Our goal is to build a community of trust, reduce mailing list traffic, and deal with disagreements swiftly when they occur.

All decision making must happen on the mailing lists. Any discussion that takes place away from the lists (for example on IRC or in person) must be brought to the lists before anything can be decided. We have a saying: if it's not on the lists, it didn't happen. We take this approach so that the greatest amount of people have a chance to participate.

Decisions should be made on the mailing list associated with the decision. For example, marketing decisions happen on the marketing list. By default, anything without a specific list should be done in public on the main development list. Anything that needs to be private will be done on the private list.

Our decision making processes are designed to reduce blockages. It is understood that people come and go as time permits. It is not practical to hear from everybody on every decision. Sometimes, this means a decision will be taken while you are away from the project. It is reasonable to bring such decisions up for discussion again, but this should be kept to a minimum.

3.1. Lazy Consensus

When you are convinced that you know what the community would like to see happen, you can assume that you already have permission and get on with the work. We call this lazy consensus. You don't have to insist that people discuss or approve your plan, and you certainly don't need to call a vote. Just assume your plan is okay unless someone says otherwise. This applies to anything in the list of decision types in section 3.6. where lazy consensus is allowed.

"It's easier to ask forgiveness than it is to get permission." — Grace Hopper

Most actions are reversible. As long as you do your work in the open, the community has plenty of opportunities to object. If someone does object, you must be prepared to roll back your work.

Lazy consensus has two effects:

  1. People are less likely to object for the sake of it
  2. It cuts down on the amount of unnecessary discussion

For this to work properly, active committers are expected to be paying attention to the project. Objecting a long time after a change has been made may require large amounts of additional work to be thrown away or redone.

Sometimes, you might not be sure what the community would want. If this is the case, you can post a note to the appropriate mailing list with an outline of what you intend to do. If nobody objects after 72 hours, you can safely assume consensus and proceed with your plan.

An important side effect of this policy is that silence is assent. There is no need for discussion, and no need for agreement to be voiced. If you make a proposal to the list and nobody responds, that should be interpreted as implicit support for your idea, and not a lack of interest. This can be hard to get used to, but is an important part of how we do things.

3.2. Discussion

If lazy consensus fails (i.e. someone objects) you can start a discussion or you can abandon the proposal.

Please try to be respectful of people's time and attention. It is a non-renewable resource and the only thing we always need more of.

Proposals should be explained clearly and come with adequate justification. Disagreements should be constructive and ideally come with alternative proposals. The goal is to reach a positive outcome for the project, not convince others of your opinion.

If a proposal is particularly controversial, try making it reversible. Reframe the proposal as an experiment (either at the project level or the feature level) and identify a timeline for evaluation along with unambiguous success and failure criteria. These sorts of proposal are usually much easier to agree on.

If a clear consensus emerges, you can proceed without a vote. Otherwise, you should abandon the proposal or move to a vote.

Voting is a failure mode of discussion. But that doesn't mean you should avoid it. It is a very powerful tool that should be used to terminate a seemingly interminable discussion. Knowing when to end a discussion and call a vote is one of the most useful skills a contributor can master.

3.3. Voting

Votes are used to indicate approval or disapproval of something.

We do this by replying with a signed number, usually +1 or -1. Occasionally people choose to vote with larger amounts (eg. +1000) to indicate strong feelings, or in fractional amounts (eg. -0.5) to convey support or disagreement without the full weight of a +1 or -1 vote. For the purpose of tallying, all values will be counted as +1, -1, or nothing.

Here are some example votes, with what they mean, and how they will be counted in the final vote tally:

Vote Meaning Counted As
+1000 "Wow, this is great. Let's do it!" +1
+1 "I like this idea." +1
+0.5 "Seems okay, but I'm not entirely convinced."
+0 "Not convinced, but doesn't seem harmful."
-0 "Not convinced, and seems harmful."
-0.5 "Not happy, but won't block this."
-1 "Not happy, and I want to prevent this from happening." -1
-1000 "Extremely unhappy with this proposal." -1

There are three types of voting: informal, formal, and vetos. An informal vote is a quick way to get people's feelings on something. A formal vote, on the other hand, requires an approval model and a decision type. More detail on approval models, RTC and technical vetos, RFCs, API changes and deprecations and decision types is available in the following sections.

All formal voting must be done in an email thread with the appropriate subject tag. Formal votes may contain multiple items for approval and these should be clearly separated. Formal voting is then carried out by replying to the vote mail. Formal votes are open for a period of at least 72 hours to allow all active voters time to consider the vote. Votes can be held open longer than this at the discretion of the person who initiated the vote.

Votes on PMC decisions are binding if they are cast by a PMC member. For all other purposes, votes are binding if they are cast by a committer. However, it is important to remember that all participants on a list get a vote. And you are encouraged to vote, even if your vote is not binding. This is a good way to get involved in the project and helps to inform the decision-making process.

You are encouraged to use an informal voting model to take a quick poll or to wrap up a discussion, whether you are a committer yet or not. These votes are informal and can be initiated by anyone. Binding votes are only needed for project-level decision-making.

3.4. Approval Models

We use three different approval models for formal voting:

RTC is only ever used in the context of a code review or a pull request, and does not require a separate vote thread. Each of the other approval models requires a vote thread.

A -1 vote is never called a veto except when using the RTC approval model. This is because a single -1 vote never has the power to block a vote outside of RTC.

Which approval model to use is dictated by the table in section 3.6. This is project policy, and can be changed by amending this document.

For electing a new Chair, the PMC may opt to use Single Transferable Vote (STV) which comes with its own rules. Apache STeVe was specifically designed to enable this process.

3.5. Review-Then-Commit and Technical Vetos

Typically, CouchDB uses the Review-Then-Commit (RTC) model of code collaboration. RTC allows work to proceed on separate feature or bugfix branches, and requires at least one other developer to review and approve the changes before they are committed to a release branch. A release branch is any branch that a release might be prepared from, such as master, 1.6.x, and so on. Notifications of these changes are sent to the commits mailing list, with GitHub discussion appearing on the notifications mailing list. It is expected that the rest of the community is regularly reviewing these changes.

Any change made to a release branch or to the master branch is a technical decision of the project. If a committer wants to object to a technical decision, they have the option of casting a -1 vote. We call this a veto. Vetos can only be made for technical reasons. A -1 vote is not considered a veto in any other context. Vetos should be used sparingly, and only after careful consideration.

All vetoes must be justified and vetoes without justification are null and void. The validity of the justification can be challenged and the outcome is decided with a vote. If the justification is valid, a veto cannot be overruled and stands until withdrawn by the caster. If you disagree with a veto, you must lobby the person casting the veto to withdraw their veto. If a veto is not withdrawn, the commit must be reverted in a timely manner.

Here's how a veto might lead to a code revert:

If the discussion did not reach consensus, Alice could challenge the validity of Bob's justification. At that point, the PMC would vote on the issue. If the PMC found that the justification was valid, Alice would have to revert the change or petition Bob to withdraw the veto. If the PMC found the justification invalid, the veto is null and void.

3.6 Request For Comment (RFC) process

For major changes to the functionality of CouchDB, a Request For Comment (RFC) process has been established. The intent of an RFC is to ensure sufficient public discussion has occurred on the design of new features, that the proposal is adequately captured in a summary document, and that there is community acceptance of the proposal. The completed RFC template for the proposal then becomes the basis for the new functionality's documentation.

The process is:

3.7 API changes and deprecations

Whenever a change is proposed to a release branch or master that removes or changes an existing HTTP API endpoint in a way that breaks backwards compatibility with a released version of CouchDB, the proposed change must be announced on the developer mailing list, and a minimum of a lazy consensus decision is required.

This policy is not intended to preserve bugs in HTTP API endpoints across released versions of CouchDB in perpetuity, nor shall it be used to assert consistency of undocumented, implementation-specific behaviour across major releases. Additions of new endpoints that fall short of the need for an RFC, or changes that do not affect backwards compatibility, do not require this notification and process, but announcement to the developer mailing list is still strongly encouraged.

3.8. Decision Types

This section describes the various decision types and the rules that apply to them.

Name Description Mailing List Lazy Consensus Approval Model Board approval Binding votes Vetoes
Technical decision A technical decision is any change made to a release branch. Commits list Allowed for trivial changes RTC No Committers Yes
Request For Comments (RFC) decision A decision on a specific proposal to alter CouchDB in a significant way. Main development list No Lazy majority No Committers No
Non-technical decision A non-technical decision is any other sort of change, or any sort of decision that falls outside of the other decision types. It is a catch-all decision type.

Non-technical decisions should normally be made with lazy consensus, or by the entire community using discussion-led consensus-building, and not through formal voting.
Whichever mailing list is most appropriate Allowed Lazy majority No Committers No
Challenge a veto Challenge the validity of a veto.

A veto is only valid when it is justified with a sound technical argument.
Main development list No Lazy 2/3 majority No PMC members No
New release Make an official release.

Release candidates can be prepared by anyone.
Main development list No Lazy majority No PMC members No
New committer Elect a new committer.

Nominations can be made by anyone by emailing the private list.
Private list No Lazy majority No PMC members No
New PMC member Elect a new PMC member.

Nominations can be made by anyone by emailing the private list.
Private list No Lazy 2/3 majority Yes PMC members No
Elect Chair Elect a new Chair. Private list No Lazy 2/3 majority or STV Yes PMC members No
Committer removal Remove a person's committer privileges. Private list No Lazy 2/3 majority No PMC members No
PMC member removal Remove a person from the PMC. Private list No Lazy 2/3 majority Yes PMC members No
Chair removal Remove the Chair. Private list No Lazy 2/3 majority Yes PMC members No
Create or amend official document Create or amend any document marked as official. Main development list No Lazy 2/3 majority No PMC members No

4. Other Topics

4.1. Subject Tags

A subject tag is a string like "[TAG]" that appears at the start of an email subject. We use these to communicate the type of message being sent.

Here's what an example subject looks like, using multiple tags:

[VOTE] [REVISED] Official CouchDB bylaws

If a VOTE or PROPOSAL thread is started without the requisite tag, its validity can be challenged. Every other tag is optional.

We have agreed on the following tags, but you are free to coin your own.

Subject tag Description Decision making Timeframe
DISCUSS This is an open discussion with no time limit No NA
REQUEST This is a request for some action to be taken (prepare release notes, testing, merge, etc) No NA
PROPOSAL This is a concrete proposal that will default to lazy consensus Yes 72 hours
VOTE This is a formal vote Yes 72 hours
NOTICE This is a notice of action taken, or action about to be taken (i.e. no discussion or consensus needed) No NA
ANNOUNCE This is a project level announcement No NA