You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Joel Shepherd <sh...@amazon.com> on 2026/03/26 18:31:22 UTC
CEPs and "user experience"
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.
Re: CEPs and "user experience"
Posted by Mick <mc...@apache.org>.
If it is just input to the vote, helping folk understand the proposed change, then it's a easy +1 from me :-)
(I just not a fan of seeing CEP pages change after the vote)
> On 26 Mar 2026, at 22:25, Paulo Motta <pa...@apache.org> wrote:
>
> My understanding of this proposal is to add a section "User Guide" or "Operational Guide" to the CEP template and I support this. I don't think this is a big change to the CEP process, it's just a suggestion, not a mandatory section. It can be removed if not applicable to a particular CEP, but it would give proposers a chance to think through the operational implications of that change.
Re: CEPs and "user experience"
Posted by Paulo Motta <pa...@apache.org>.
My understanding of this proposal is to add a section "User Guide" or
"Operational Guide" to the CEP template and I support this. I don't think
this is a big change to the CEP process, it's just a suggestion, not a
mandatory section. It can be removed if not applicable to a particular CEP,
but it would give proposers a chance to think through the operational
implications of that change.
On Thu, Mar 26, 2026 at 5:20 PM Mick <mc...@apache.org> wrote:
> It is nice the CEP remains what we vote on, for the sake of governance.
>
> 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)
> ?
> 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…
>
>
>
>
> > On 26 Mar 2026, at 19:31, Joel Shepherd <sh...@amazon.com> 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.
> >
>
>
Re: CEPs and "user experience"
Posted by Joel Shepherd <sh...@amazon.com>.
Thanks all: I've updated the Wiki as outlined below (minus a couple
typos). It's a Wiki, so vote with your edits if you think it needs
refinement.
-- Joel.
On 4/5/2026 12:58 AM, Bernardo Botella wrote:
>
> +1 on this
>
> El El jue, 2 abr 2026 a las 22:10, Josh McKenzie
> <jm...@apache.org> escribió:
>
> 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
>> dev@cassandra.apache.org 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
>>>> <sh...@amazon.com> 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
>>>> <sh...@amazon.com> 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.
>>>> >>
>>>>
>>>
>
Re: CEPs and "user experience"
Posted by Bernardo Botella <co...@bernardobotella.com>.
+1 on this
El El jue, 2 abr 2026 a las 22:10, Josh McKenzie <jm...@apache.org>
escribió:
> 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
> dev@cassandra.apache.org 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 <sh...@amazon.com> 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 <sh...@amazon.com> 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.
> >>
>
>
>
>
Re: CEPs and "user experience"
Posted by Josh McKenzie <jm...@apache.org>.
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 dev@cassandra.apache.org 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 <sh...@amazon.com> 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 <sh...@amazon.com> 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.
>>>> >>
>>
Re: CEPs and "user experience"
Posted by Joel Shepherd <sh...@amazon.com>.
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
dev@cassandra.apache.org 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 <sh...@amazon.com>
>> 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 <sh...@amazon.com>
>> 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.
>> >>
>>
>
Re: CEPs and "user experience"
Posted by Josh McKenzie <jm...@apache.org>.
> 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 <sh...@amazon.com> 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 <sh...@amazon.com> 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.
>> >>
Re: CEPs and "user experience"
Posted by Isaac Reath <is...@gmail.com>.
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 <sh...@amazon.com> 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 <sh...@amazon.com> 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.
> >>
>
Re: CEPs and "user experience"
Posted by Joel Shepherd <sh...@amazon.com>.
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 <sh...@amazon.com> 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.
>>
Re: CEPs and "user experience"
Posted by Mick <mc...@apache.org>.
It is nice the CEP remains what we vote on, for the sake of governance.
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) ?
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…
> On 26 Mar 2026, at 19:31, Joel Shepherd <sh...@amazon.com> 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.
>
Re: CEPs and "user experience"
Posted by Patrick McFadin <pm...@gmail.com>.
I love this idea, and it looks like Joel is on team DX!
On Thu, Mar 26, 2026 at 2:07 PM Dinesh Joshi <dj...@apache.org> wrote:
> Seems useful and reasonable! We should have this.
>
> On Thu, Mar 26, 2026 at 11:31 AM Joel Shepherd <sh...@amazon.com>
> 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.
>>
>>
Re: CEPs and "user experience"
Posted by Dinesh Joshi <dj...@apache.org>.
Seems useful and reasonable! We should have this.
On Thu, Mar 26, 2026 at 11:31 AM Joel Shepherd <sh...@amazon.com> 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.
>
>