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.
>>
