Small, surgical, not overly prescriptive. +1 from me.
On Wed, Apr 1, 2026, at 7:51 PM, Joel Shepherd wrote: > Thanks all for the discussion and suggestions on this. > > It doesn't look like the Apache Confluence has a "draft" mode to enable edits > to be reviewed before publishing, so I'm going to outline my proposed changes > to the main "Cassandra Enhancement Proposals (CEP)" page > (https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=95652201) > here before making them in the Wiki itself. > > Here goes: > > * Under "What should be included in a CEP?", add a bullet point like > "Operational Implications covering required migration steps, configuration > changes, and new or deprecated operational tooling or metrics (as > applicable)," > > * Under "The Process", add a Step 7, along the lines of: If your CEP is > accepted and work on the implementing it progresses, you may discover > additional required work or changes to the approach documented in the CEP. In > this case, please add an "Addendum" section to the end of the CEP, document > the additions to and changes from the accepted CEP that you are encountering > during implementation as you find them, and send an e-mail with a subject > line "[REVISION] CEP-<##> <Title>" to the [email protected] e-mail > list. Note that this may generate further discussion and possibly suggestions > for alternate approaches. Please DO NOT otherwise alter "accepted" CEPs so > that the original CEP content is always easily available for review. > > Very open to your feedback and suggestions on this. > > Thanks -- Joel. > > On 3/29/2026 2:32 PM, Josh McKenzie wrote: >> >>> I agree that this section may not be applicable to many CEPs, but I think >>> it's worth explicitly calling out why it's not. >> IMO this is one of those "assume you need to think this through for a CEP >> unless you have strong justification why not" things. >> >> On Fri, Mar 27, 2026, at 10:18 AM, Isaac Reath wrote: >>> I'm a big fan of the idea of having this on new CEPs. >>> >>> To Paulo's point about the section being optional: I agree that this >>> section may not be applicable to many CEPs, but I think it's worth >>> explicitly calling out why it's not. In that sense, it's still optional but >>> taken into consideration when discussing the CEP. >>> >>> On Thu, Mar 26, 2026 at 5:47 PM Joel Shepherd <[email protected]> wrote: >>>> On 3/26/2026 2:20 PM, Mick wrote: >>>> > It is nice the CEP remains what we vote on, for the sake of governance. >>>> >>>> Makes sense. What would you think of allowing an explicit "Addendum" or >>>> "Errata" section where refinements or needed changes are discovered >>>> during implementation? And maybe an expectation that updates to those >>>> will be announced on this list so folks can review. That'll preserve the >>>> original proposal as it was accepted, yet allow for evolution as plans >>>> meet reality. >>>> >>>> > is the "user experience" (or "operational guide") part of what we vote >>>> > on ? is it as fixed as the rest of the cep doc (the input in/before the >>>> > impl) ? >>>> >>>> I personally think it should be. For the author, it's a forcing function >>>> for thinking through the operator experience up-front, which will >>>> probably result in a better operator experience, and that in turn will >>>> make Cassandra more appealing to current and future users. >>>> >>>> For the reader/reviewer, it's an early opportunity to decide if they'll >>>> actually be able to use the feature as proposed, or if there are >>>> operational risks that they're not comfortable with. >>>> >>>> > if not, would it be better somewhere else ? >>>> > i can see the need for both "here's a permanent copy of the CEP as it >>>> > was voted on" and "here's how it ended up, with extra docs", but I don't >>>> > know how/where the latter goes… >>>> >>>> Yeah: I'll withdraw my comment about "retro-fitting" -- I didn't think >>>> about that in terms of changing the voted-on proposal -- but since the >>>> CEP often seems to be the comprehensive* source of information about a >>>> feature/capability, it seems like a good place for information about how >>>> to use the thing. >>>> >>>> Thanks -- Joel. >>>> >>>> * - Despite the use of the word "comprehensive" as well as em dashes, >>>> this e-mail was composed entirely by a human and not an AI agent. ;-) >>>> >>>> >> On 26 Mar 2026, at 19:31, Joel Shepherd <[email protected]> wrote: >>>> >> >>>> >> Hi all - I wonder if there would be community support for including a >>>> >> "user experience" section in CEPs going forward (no rules against >>>> >> retro-fitting them either). >>>> >> >>>> >> The purpose of the section would be to describe how an operator would >>>> >> be expected to enable, configure, upgrade (if necessary) and operate >>>> >> the feature proposed in the CEP. >>>> >> >>>> >> Paulo wrote an "Operational Guide" section in CEP-62, which I found >>>> >> helpful in getting a clear picture about what my responsibilities would >>>> >> be, as an operator, if I wanted to use Sidecar to manage my node >>>> >> config. As I'm working through the implementation of CEP-50, I'm also >>>> >> realizing that operators are going to need to understand how to >>>> >> configure negotiation and know about things that will end up either >>>> >> being sharp edges or fundamental changes in behavior. (Did you know >>>> >> that unauthenticated, anonymous users are by default super-users? Holy >>>> >> Privilege Escalation, Batman!) >>>> >> >>>> >> I plan to add an "Operational Guide" section to CEP-50 and probably >>>> >> revise it as I better understand the implications of some of the >>>> >> changes required. I think in general doing so as early as possible will >>>> >> get us to think early about how easy or hard it will be for Cassandra >>>> >> users to adopt new functionality, and hopefully push the project as a >>>> >> whole towards making it as easy as possible. >>>> >> >>>> >> Thoughts? >>>> >> >>>> >> -- Joel. >>>> >> >>
