Any of the following should be considered a major change:
- Any major new feature, subsystem, or piece of functionality
- Any change that impacts the public interfaces of the project
Cassandra's Public Interfaces
Not all compatibility commitments are the same. We need to spend significantly more time on the wire protocols as these break code in lots of clients, cause downtime releases, etc. Public API/SPIs are next as they cause people to rebuild code and/or maintain abstraction layers in third-party libraries/frameworks. Configuration, monitoring, and command line tools can be faster and looser — changes here will break monitoring dashboards and require a bit of care during upgrades but aren't as big a burden.
For the most part monitoring, command line tool changes, and configs are added with new features so these can be done with a single CEP
Info | ||
---|---|---|
| ||
The CIP process itself has not been approved by the community yet. This is a strawman draft to start the conversation to such a process. |
This page describes a proposed Cassandra Improvement Proposal (CIP) process for proposing a major change to Cassandra. It has been adopted from similar processes for Kafka and Spark.
To create your own CIP, click on
Create from template | ||||||||
---|---|---|---|---|---|---|---|---|
|
dev@cassandra.apache.org
and request permission. Also add an entry to the table WIP – Design Proposals – Cassandra Improvement Proposals (CIP).Table of Contents |
---|
Purpose
The purpose of an CIP is to inform and involve the user community in major improvements to the Cassandra codebase throughout the development process, to increase the likelihood that user needs and compatibility are met. It is similar to a product requirement document commonly used in product management.
CIPs should be used for significant user-facing or cross-cutting changes, not small incremental improvements. When in doubt, if a committer thinks a change needs an CIP, it does.
Cassandra requires a high level of compatibility between releases, especially to ensure rolling upgrades are possible. Core architectural elements can't break compatibility or shift functionality from release to release. As a result each new major feature or public api has to be done in a way that we can stick with it going forward.
...
- 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
- ...??…
When making changes or additions that impact these areas we need to think through what we are doing as best we can prior to release. And as we go forward we need to stick to our decisions as much as possible. All technical decisions have pros and cons so it is important we capture the thought process that lead to a decision or design to avoid flip-flopping needlessly.
Hopefully we can make these proportional in effort to their magnitude — small changes should just need a couple brief paragraphs, whereas large changes need detailed design discussions.
This process also isn't meant to discourage incompatible changes — proposing an incompatible change is totally legitimate. Sometimes we will have made a mistake and the best path forward is a clean break that cleans things up and gives us a good foundation going forward. Rather this is intended to avoid accidentally introducing half thought-out interfaces and protocols that cause needless heartburn when changed. Likewise the definition of "compatible" is itself squishy: small details like which errors are thrown when are clearly part of the contract but may need to change in some circumstances, likewise performance isn't part of the public contract but dramatic changes may break use cases. So we just need to use good judgement about how big the impact of an incompatibility will be and how big the payoff is.
What is considered a "major change" that needs a CIP?
Any of the following should be considered a major change:
- Any major new feature, subsystem, or piece of functionality
- Any change that impacts the public interfaces of the project
Not all compatibility commitments are the same. We need to spend significantly more time on the wire protocols as these break code in lots of clients, cause downtime releases, etc. Public API/SPIs are next as they cause people to rebuild code and/or maintain abstraction layers in third-party libraries/frameworks. Configuration, monitoring, and command line tools can be faster and looser — changes here will break monitoring dashboards and require a bit of care during upgrades but aren't as big a burden.
For the most part monitoring, command line tool changes, and configs are added with new features so these can be done with a single CIP.
What should be included in a CIP?
A CIP should contain the following sections:
- Motivation: The problem to be solved.
- Audience: The intended client audience. Examples include data scientists, data engineers, library devs, devops, etc. A single CIP can have multiple target personas.
- Goals: What must this allow users to do, that they can't currently.
- Non-Goals: What problem(s) is this proposal not designed to solve.
- 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.
Who should initiate the CIP?
Anyone can initiate a CIP but you shouldn't do it unless you have an intention and know-how of getting the work done to implement it.
A CIP 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 CIP. Responsibilities of the shepherd include, but are not limited to:
- Be the advocate for the proposed change
- Help push forward on design and achieve consensus among key stakeholders
- Review code changes, making sure the change follows project standards
- Get feedback from users and iterate on the design & implementation
- Uphold the quality of the changes, including verifying whether the changes satisfy the goal of the CIP and are absent of critical bugs before releasing them
Process
Here is the process for making a CIP:
- Click
. Take the next available CIP number and give your proposal a descriptive heading. e.g. "CIP 1: Proposing an Apache Cassandra Management process".Create from template templateName 96600065 templateId 96600065 title CIP-NEXT: Insert Title Here buttonLabel Create CIP - Fill in the sections as described above
- Start a [DISCUSS] thread on the Apache mailing list. Please ensure that the subject of the thread is of the format [DISCUSS] CIP-{your CIP number} {your CIP 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. When you feel you have a finalized proposal
- 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.
- Please update the CIP wiki page, and the index below, to reflect the current stage of the CIP after a vote. This acts as the permanent record indicating the result of the CIP (e.g., Accepted or Rejected). Also report the result of the CIP vote to the voting thread on the mailing list so the conclusion is clear.
CIP round-up
Next CIP Number: 2
Use this number as the identifier for your CIP and increment this value.
Adopted CIPs
...
Release
CIPs under discussion
...
Sent emails to Dev discussion group.
Work tracked under CASSANDRA-14395.
Dormant/inactive CIPs
...
Discarded CIPs
...