This page describes a proposed Cassandra Enhancement Proposal (CEP) process for proposing a major change to Cassandra.

Purpose

Cassandra Enhancement Proposals are intended as a better landing space for New Features, as opposed to JIRA.

The purpose of a CEP confluence page is to help promote as much possible open collaboration during the initial brainstorming and navigation phase of a new feature. The benefit this brings to the author/initiator of the idea, increasing the likelihood of the idea getting implemented and committed, is intended to be enough incentive to write the CEP instead of the JIRA ticket.

CEPs should be used for significant user-facing or cross-cutting changes, not small incremental improvements.  At the technical level, CEPs are intended to increase the likelihood that compatibility requirements are safely met. At a user level, CEPs are to help ensure all variants of Cassandra installations and usages are considered.

CEPs are also not intended to be a return to waterfall development, and an acceptance of an CEP provides no guarantee to the work eventually being accepted. It is all too often that work-invalidating insights hit late, invalidating an idea, despite after a working group having formed, agreed, and a significant work has been done. This is always a risk of part of agile development, but a CEP up front with engagement from a bunch of parties should help surface those design implications sooner.

The process of starting a CEP is intended to be light-weight and flexible. For example, a CEP can be started with nothing more than a title to begin with, and where it goes from there is left up to the working group that materialises. See Scott Andreas' 2019 NGCC presentation for a community perspective, and how this ties into the release lifecycle and evolution of the project. The information and guidelines that follow are only intended as food-for-thought to get started.

What should be included in a CEP?

A CEP should contain the following sections: 

• Scope,

• Goals (and non-goals),

• Approach,

• Timeline,

• Mailing list / Slack channels,

• Related JIRA tickets.

Who should initiate the CEP?

Anyone can initiate a CEP but you shouldn't do it unless you have an intention and know-how of getting the work done to implement it.

A CEP needs to attract a Shepherd that is a PMC member who is committed to shepherding the proposed change throughout the entire process. Although the shepherd can delegate or work with other committers in the development process, the shepherd is ultimately responsible for the success or failure of the CEP. Responsibilities of the shepherd include, but are not limited to:

• Be an advocate for the proposed change
• Ensure the working group achieves consensus among key stakeholders
• Ensure the working group seeks feedback from users and iterates on the design & implementation (see below for additional CEP documentation)
• Uphold the quality of the changes, including verifying whether the changes satisfy the goal of the CEP and are absent of critical bugs before releasing them
• Be committed to review code changes, ensuring project standards

The Process

Here is the process for making a CEP:

1. To create your own CEP, click on Create CEP.
   If you don't have permission, please send an email with your Wiki ID to dev@cassandra.apache.org and request permission. Also add an entry to the table CEPs under discussion.

   Take the next available CEP number and give your proposal a descriptive heading. e.g. "CEP 1: Proposing an Apache Cassandra Management process".
   
   
2. Fill in the sections as described above.
   
   
3. Start a [DISCUSS] thread on the Apache mailing list. Please ensure that the subject of the thread is of the format [DISCUSS] CEP-{your CEP number} {your CEP heading} The discussion should happen on the mailing list not on the wiki since the wiki comment system doesn't work well for larger discussions. In the process of the discussion you may update the proposal. You should let people know the changes you are making.
   
   
4. As the CEP nears completion, consider adding any additional design documentation (see below) to the CEP, especially where it summaries working group discussions.
   
   
5. Once the proposal is finalized call a [VOTE] to have the proposal adopted. These proposals are more serious than code changes and more serious even than release votes. The criteria for acceptance is lazy consensus (3 binding +1 votes and no binding vetoes). The vote should remain open for 72 hours.
   
   
6. Please update the CEP wiki page, and the index below, to reflect the current stage of the CEP after a vote. This acts as the permanent record indicating the result of the CEP (e.g., Accepted or Rejected). Also report the result of the CEP vote to the voting thread on the mailing list so the conclusion is clear.

Example CEP Design Documentation

After the CEP is opened and a working group is active, to help flesh out the implementation constraints, here are some suggestions for additional discussion and documentation that can go into the CEP:

• Motivation: The problem to be solved.
• Audience: The intended client audience. Examples include data scientists, data engineers, library devs, devops, etc. A single CEP can have multiple target personas. 
  
• Proposed Change: The new thing you want to do. This may be fairly extensive and have large subsections of its own. Or it may be a few sentences, depending on the scope of the change.
• New or Changed Public Interfaces: Impact to any of the "compatibility commitments" described above. We want to call these out in particular so everyone thinks about them.
• Migration Plan and Compatibility: If this feature requires additional support for a no-downtime upgrade describe how that will work.
• Rejected Alternatives: What are the other alternatives you considered and why are they worse? The goal of this section is to help people understand why this is the best solution now, and also to prevent churn in the future when old alternatives are reconsidered.

Compatibility Concerns

Cassandra requires a high level of compatibility between releases to ensure rolling upgrades are possible, as well as supporting third-party libraries and tools.

These areas of compatibility are 

• native protocol (and CQL)
• gossip and the messaging service
• pluggable components (SPIs) like authorisation, triggers, …
• commitlog, hintlog, cache files
• sstables components 
• configuration
• jmx mbeans (including metrics)
• monitoring
• client tool classes
• command line tools and arguments
• operational routines
• …

List of CEPs

Adopted CEPs

CEPs under discussion

Dormant/inactive CEPs

Discarded CEPs