You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Josh McKenzie <jm...@apache.org> on 2022/12/02 19:24:34 UTC
[DISCUSS] API modifications and when to raise a thread on the dev ML
Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
> Public APIs
>
> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
My .02:
1. We should rename that page to a "code contribution guide" as discussed on the slack thread
2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
We've learned that API's are *really really hard* to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
So that's 1 opinion. What other opinions are out there?
~Josh
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Ekaterina Dimitrova <e....@gmail.com>.
Aleksey, I absolutely agree with the point users will be able to give more
input, help early on with feedback etc. But I struggle to see why having
two sentences explicitly to mention on the ticket the exact API change,
which can be even in a new separate required field is not enough to trigger
discussion if needed. We can even have mandatory:
“Is this API change” and if the answer is “yes” - people should explain in
a few sentences
It seems neat to me, streamlined and easy to find historically in tickets.
Especially if we consider many of them will be accepted with lazy consensus
as it was pointed out earlier on this thread.
On Tue, 6 Dec 2022 at 10:18, Aleksey Yeshchenko <al...@apple.com> wrote:
> Public APIs are 1) essentially forever-lasting and 2) are what our users
> actually get to interact with. A suboptimal public API can be annoying to
> work with at best, and at worst force and cement suboptimal implementations.
>
> The goal here is to make sure that whatever public API changes we
> introduce are as good as they can be, first time around. Getting as many
> diverse eyes on it as possible helps with achieving this goal. Making these
> changes more visible and allowing for longer periods of revision maximises
> the opportunity for someone to spot an issue or suggest an improvement.
>
> This isn’t about trust, but about recognition of one’s own limitations.
> Most active committers - *absolute* most of us - are indeed *not* Cassandra
> users or Cassandra operators. Our predominant interaction with Cassandra is
> via editing Java code in our IDEs. We don’t usually have a lot of
> experience or skin in the game when it comes to consuming Cassandra’s APIs.
> We should welcome and actively seek inputs of those who do. Giving more
> time to other developers to react and contribute is pretty important as
> well.
>
> The mechanisms suggested here don’t strike me as being too costly.
> Starting a lightweight informal thread even for every individual proposal
> is no huge deal, surely. We aren’t talking about CEP level of commitment
> here.
>
> It’s not the first time you bring up trust, I feel, but there really is no
> need to go all defensive here. No person or organisation is being singled
> out. Admitting that API design can genuinely benefit from user input and
> input of others in general, to me, is productive humility - a sign of
> maturity. It’s not a reason to be offended.
>
> > On 6 Dec 2022, at 13:53, Benjamin Lerer <b....@gmail.com> wrote:
> >
> > I am sorry but I still do not understand what problem we are trying to
> solve.
> > All examples given so far have been about significant features which we
> already discuss on this mailing not about minor changes that happen
> multiple times per week.
> > Is it a trust issue ?
>
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Aleksey Yeshchenko <al...@apple.com>.
> I am simply trying to understand the need to put in place a process that has a high cost in terms of time and effort for small changes.
It is an additional cost, but it’s not a high cost. And certainly not a high *marginal* cost - when compared to all the admin involved in getting a patch committed. A tiny extra step. One quick email is nothing. If a conversation comes out of it, then yes, engaging with it will take time, but then again, it’ll also mean that the effort has not been wasted and attracted input.
> So far nobody has been able to provide me with examples of times where it would have been needed. I am sorry. I see the cost not the benefit.
Many deprecated config params and bits of DDL, for example, would qualify. Some CQL beyond DDL - including early authn/authz bits introduced by me - could’ve been designed better first time around and not need a rewrite/deprecation.
> On 6 Dec 2022, at 16:21, Benjamin Lerer <b....@gmail.com> wrote:
>
>> It’s not the first time you bring up trust, I feel, but there really is no need to go all defensive here.
>
> I am not defensive. I am simply trying to understand the need to put in place a process that has a high cost in terms of time and effort for small changes.
> So far nobody has been able to provide me with examples of times where it would have been needed. I am sorry. I see the cost not the benefit.
>
>
> Le mar. 6 déc. 2022 à 16:18, Aleksey Yeshchenko <aleksey@apple.com <ma...@apple.com>> a écrit :
>> Public APIs are 1) essentially forever-lasting and 2) are what our users actually get to interact with. A suboptimal public API can be annoying to work with at best, and at worst force and cement suboptimal implementations.
>>
>> The goal here is to make sure that whatever public API changes we introduce are as good as they can be, first time around. Getting as many diverse eyes on it as possible helps with achieving this goal. Making these changes more visible and allowing for longer periods of revision maximises the opportunity for someone to spot an issue or suggest an improvement.
>>
>> This isn’t about trust, but about recognition of one’s own limitations. Most active committers - *absolute* most of us - are indeed *not* Cassandra users or Cassandra operators. Our predominant interaction with Cassandra is via editing Java code in our IDEs. We don’t usually have a lot of experience or skin in the game when it comes to consuming Cassandra’s APIs. We should welcome and actively seek inputs of those who do. Giving more time to other developers to react and contribute is pretty important as well.
>>
>> The mechanisms suggested here don’t strike me as being too costly. Starting a lightweight informal thread even for every individual proposal is no huge deal, surely. We aren’t talking about CEP level of commitment here.
>>
>> It’s not the first time you bring up trust, I feel, but there really is no need to go all defensive here. No person or organisation is being singled out. Admitting that API design can genuinely benefit from user input and input of others in general, to me, is productive humility - a sign of maturity. It’s not a reason to be offended.
>>
>> > On 6 Dec 2022, at 13:53, Benjamin Lerer <b.lerer@gmail.com <ma...@gmail.com>> wrote:
>> >
>> > I am sorry but I still do not understand what problem we are trying to solve.
>> > All examples given so far have been about significant features which we already discuss on this mailing not about minor changes that happen multiple times per week.
>> > Is it a trust issue ?
>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benjamin Lerer <b....@gmail.com>.
>
> It’s not the first time you bring up trust, I feel, but there really is no
> need to go all defensive here.
I am not defensive. I am simply trying to understand the need to put in
place a process that has a high cost in terms of time and effort for small
changes.
So far nobody has been able to provide me with examples of times where it
would have been needed. I am sorry. I see the cost not the benefit.
Le mar. 6 déc. 2022 à 16:18, Aleksey Yeshchenko <al...@apple.com> a
écrit :
> Public APIs are 1) essentially forever-lasting and 2) are what our users
> actually get to interact with. A suboptimal public API can be annoying to
> work with at best, and at worst force and cement suboptimal implementations.
>
> The goal here is to make sure that whatever public API changes we
> introduce are as good as they can be, first time around. Getting as many
> diverse eyes on it as possible helps with achieving this goal. Making these
> changes more visible and allowing for longer periods of revision maximises
> the opportunity for someone to spot an issue or suggest an improvement.
>
> This isn’t about trust, but about recognition of one’s own limitations.
> Most active committers - *absolute* most of us - are indeed *not* Cassandra
> users or Cassandra operators. Our predominant interaction with Cassandra is
> via editing Java code in our IDEs. We don’t usually have a lot of
> experience or skin in the game when it comes to consuming Cassandra’s APIs.
> We should welcome and actively seek inputs of those who do. Giving more
> time to other developers to react and contribute is pretty important as
> well.
>
> The mechanisms suggested here don’t strike me as being too costly.
> Starting a lightweight informal thread even for every individual proposal
> is no huge deal, surely. We aren’t talking about CEP level of commitment
> here.
>
> It’s not the first time you bring up trust, I feel, but there really is no
> need to go all defensive here. No person or organisation is being singled
> out. Admitting that API design can genuinely benefit from user input and
> input of others in general, to me, is productive humility - a sign of
> maturity. It’s not a reason to be offended.
>
> > On 6 Dec 2022, at 13:53, Benjamin Lerer <b....@gmail.com> wrote:
> >
> > I am sorry but I still do not understand what problem we are trying to
> solve.
> > All examples given so far have been about significant features which we
> already discuss on this mailing not about minor changes that happen
> multiple times per week.
> > Is it a trust issue ?
>
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Aleksey Yeshchenko <al...@apple.com>.
Public APIs are 1) essentially forever-lasting and 2) are what our users actually get to interact with. A suboptimal public API can be annoying to work with at best, and at worst force and cement suboptimal implementations.
The goal here is to make sure that whatever public API changes we introduce are as good as they can be, first time around. Getting as many diverse eyes on it as possible helps with achieving this goal. Making these changes more visible and allowing for longer periods of revision maximises the opportunity for someone to spot an issue or suggest an improvement.
This isn’t about trust, but about recognition of one’s own limitations. Most active committers - *absolute* most of us - are indeed *not* Cassandra users or Cassandra operators. Our predominant interaction with Cassandra is via editing Java code in our IDEs. We don’t usually have a lot of experience or skin in the game when it comes to consuming Cassandra’s APIs. We should welcome and actively seek inputs of those who do. Giving more time to other developers to react and contribute is pretty important as well.
The mechanisms suggested here don’t strike me as being too costly. Starting a lightweight informal thread even for every individual proposal is no huge deal, surely. We aren’t talking about CEP level of commitment here.
It’s not the first time you bring up trust, I feel, but there really is no need to go all defensive here. No person or organisation is being singled out. Admitting that API design can genuinely benefit from user input and input of others in general, to me, is productive humility - a sign of maturity. It’s not a reason to be offended.
> On 6 Dec 2022, at 13:53, Benjamin Lerer <b....@gmail.com> wrote:
>
> I am sorry but I still do not understand what problem we are trying to solve.
> All examples given so far have been about significant features which we already discuss on this mailing not about minor changes that happen multiple times per week.
> Is it a trust issue ?
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Ekaterina Dimitrova <e....@gmail.com>.
If the big works are already accompanied by discussions, I do not see a
reason a list pointing to Jira tickets with small API changes could not
serve our needs. A nice label and commitment that API change will be
brought in the description with a few sentences seems more than enough to
me.
Also, I am confused… when I asked about the access of JDK internals which
can lead to trouble, breaking changes and urgent patches needed, we agreed
Jira is enough and we shouldn’t trigger too much noise here, but for small
API changes this is preferable? What do I miss here? Maybe there is
something more that people have in mind that I struggle to see?
On Tue, 6 Dec 2022 at 8:53, Benjamin Lerer <b....@gmail.com> wrote:
> I am sorry but I still do not understand what problem we are trying to
> solve.
> All examples given so far have been about significant features which we
> already discuss on this mailing not about minor changes that happen
> multiple times per week.
> Is it a trust issue ?
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benjamin Lerer <b....@gmail.com>.
I am sorry but I still do not understand what problem we are trying to
solve.
All examples given so far have been about significant features which we
already discuss on this mailing not about minor changes that happen
multiple times per week.
Is it a trust issue ?
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Josh McKenzie <jm...@apache.org>.
> The lower the bar to participation on this stuff the better, as it isn’t deeply technical and we have lots of lurkers here that have relevant experience and knowledge that can chime in with valuable feedback if given the chance
Good point. Separate thread for API Revisions is the lowest bar for participation w/greatest inclusivity I've seen in the thread; I'm in favor of that on those grounds.
On Mon, Dec 5, 2022, at 4:58 PM, Benedict wrote:
>
> My view is simply that API discussion should be undertaken in a broader forum than Jira. The lower the bar to participation on this stuff the better, as it isn’t deeply technical and we have lots of lurkers here that have relevant experience and knowledge that can chime in with valuable feedback if given the chance. The transaction syntax thread demonstrated this with participants we do not often see.
>
> Jira is exceptionally noisy, and most discussion is not particularly important for broad consumption - implementation decisions can always be revisited, and are anyway fine to be suboptimal. So quite rationally most folk do not pay attention.
>
> We want their input for this stuff though. So, yes, I think we should ideally keep API discussions to this list, preferably exclusively (modulo preparatory discussions), as that retains a high signal:noise funnel of information for people to subscribe to and participate in at low cost.
>
> Links to a list of API topics in the status email just doesn’t serve this purpose.
>
>> On 5 Dec 2022, at 16:15, Josh McKenzie <jm...@apache.org> wrote:
>>
>>> can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report?
>>
>>> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
>> My understanding of Ekaterina's suggestions it that I add a [Pending API Changes] section to the email thread every 2-3 weeks w/everything that's opened within that time frame with that tag. Batch processing by interested parties periodically rather than bulk batch processing at the end of a release cycle.
>>
>> I'm happy to take that on and I think that model could work. I'm also happy with a DISCUSS thread once a week on some pending API change someone has in flight; to me that doesn't seem like too big a burden, especially if a solid majority of them are lazy consensus noops.
>>
>>> Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also?
>> I'm an emphatic "Yes" on this. I've had to use some poorly fit exception types in the past because of legacy coupling / commitment with the existing API's that make it harder both for us to work on things in the codebase and harder for our users to understand what we're trying to communicate with them. Further, users have splunk queries and other automated parsing set up to check logs for specific exceptions and warning texts; changing those things breaks an unknown number of downstream consumers and creates toil, or worse, introduces outages, for users.
>>
>> On Mon, Dec 5, 2022, at 10:34 AM, Andrés de la Peña wrote:
>>>> This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>>>
>>> That after the fact review approach doesn't seem very dependant on whether we have a DISCUSS thread for every change or not, since those supervision scans will probably still happen. After all anyone can ask for modifications on anything at any moment, previously agreed or not. For example, the CEP for guardrails was publicly discussed, voted, approved, reviewed and committed with nested config and a global enable flag, and still we had to revert those two things shortly after commit.
>>>
>>> On Mon, 5 Dec 2022 at 15:12, Ekaterina Dimitrova <e....@gmail.com> wrote:
>>>> “ I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.”
>>>> Just to clarify, I do not suggest to use the status mail to respond with concerns. But more like - having a link to the filter in the bi-weekly report and then everyone can open it and check the list of tickets and comment directly on the tickets or open a thread if they think the issue deserves one.
>>>> Same as having link to the tickets that are blockers or tickets that need reviewers. Whoever wants will have an easy way to get to those and take whatever actions they want.
>>>>
>>>> On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
>>>>>
>>>>> Perhaps you misunderstand my concern? I think these decisions need broader input, not just my input.
>>>>>
>>>>> Are you therefore asking why I do not monitor these topics and propose DISCUSS threads based on activities others are undertaking? This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>>>>>
>>>>> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
>>>>>
>>>>>
>>>>>
>>>>>> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>>>>>>
>>>>>> Benedict, I am confused. If you are so much concerned about virtual tables or CQL why do you not track those components changes directly? People usually label them correctly I believe. Like that you would be able to provide feedback straight away rather than after the fact. It would be a win for everybody, no?
>>>>>>
>>>>>> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com> a écrit :
>>>>>>> Quick idea - can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report? In the meantime if there are big changes that people consider they need a DISCUSS thread for they can always open one? I will be happy to help with the mentioned filter/report.
>>>>>>> Also +1 on having Contributing doc with broader discussion and directions around API
>>>>>>>
>>>>>>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>>>>>>>
>>>>>>>> I would be fine with a formal API change review period prior to release, but if we go that route people should expect to have to revisit work they completed a while back, and there should be no presumption that decisions taken without a DISCUSS thread should be preferred to alternative suggestions - and we should have a clear policy of reverting any work if it is not revisited based on the outcome of any discussion, since seeking broader input earlier was always an option. I expect this approach could lead to frustration, but it might actually be a better system than separate DISCUSS threads as the changes can be considered holistically.
>>>>>>>>
>>>>>>>> The idea that a DISCUSS thread for each change would be burdensome however is I think mistaken. Even if 70 were the true figure, it would have been around one per week, and they could easily have been batched. I’d also be fine with white listing some changes (eg JMX and warning messages) - but definitely not virtual tables or CQL. These APIs develop strong user dependencies, and are very hard to change.
>>>>>>>>
>>>>>>>> We should not restrict input on our main user experiences to the handful of people with time to closely monitor Jira, most of whom are not even users of Cassandra. We should be seeking the broadest visibility, including casual observers and non-contributors.
>>>>>>>>
>>>>>>>>
>>>>>>>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>>>>>>>
>>>>>>>>> It feels bit of overkill to me to require addition of any new virtual tables/JMX/configuration/knob to go through a discuss thread. If this would require 70 threads for the previous release I think this would easily become spammy and counter-productive.
>>>>>>>>>
>>>>>>>>> I think the burden should be on the maintainer to keep up with changes being added to the database and chime in any areas it feel responsible for, as it has been the case and has worked relatively well.
>>>>>>>>>
>>>>>>>>> I think it makes sense to look into improving visibility of API changes, so people can more easily review a summary of API changes versus reading through the whole changelog (perhaps we need a summarized API change log?).
>>>>>>>>>
>>>>>>>>> It would also help to have more explicit guidelines on what kinds of API changes are riskier and might require additional visibility via a DISCUSS thread.
>>>>>>>>>
>>>>>>>>> Also, would it make sense to introduce a new API review stage during release validation, and agree to revert/update any API changes that may be controversial that were not caught during normal review?
>>>>>>>>>
>>>>>>>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
>>>>>>>>>> Indeed that contribution policy should be clearer and not be on a page titled code style, thanks for briging that up.
>>>>>>>>>>
>>>>>>>>>> If we consider all those things APIs, and additions are also considered changes that require a DISCUSS thread, it turns out that almost any not-bugfix ticket would require a mail list thread. In fact, if one goes through CHANGES.txt it's easy to see that most entries would have required a DISCUSS thread.
>>>>>>>>>>
>>>>>>>>>> I think that such a strict policy would only make us lose agility and increase the burden of almost any contribution. After all, it's not that changes without a DISCUSS thread happen in secret. Changes are publicly visible on their tickets, those tickets are notified on Slack so anyone can jump into the ticket discussions and set themselves as reviewers, and reviewers can ask for DISCUSS threads whenever they think more opinions or broader consensus are needed.
>>>>>>>>>>
>>>>>>>>>> Also, a previous DISCUSS thread is not going to impede that any changes are going to be questioned later. We have seen changes that are proposed, discussed and approved as CEPs, reviewed for weeks or months, and finally committed, and still they are questioned shortly after that cycle, and asked to be changed or discussed again. I don't think that an avalanche of DISCUSS threads is going to improve that, since usually the problem is that people don't have the time for deeply looking into the changes when they are happening. I doubt that more notification channels are going to improve that.
>>>>>>>>>>
>>>>>>>>>> Of course I'm not saying that there should never DISCUSS threads before starting a change. Probably we can all agree that major changes and things that break compatibility would need previous discussion.
>>>>>>>>>>
>>>>>>>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>>>>>>>>> Thanks for opening this thread Josh,
>>>>>>>>>>>
>>>>>>>>>>> It seems perfectly normal to me that for important changes or questions we raise some discussion to the mailing list.
>>>>>>>>>>>
>>>>>>>>>>> My understanding of the current proposal implies that for the 4.1 release we should have had to raise over 70 discussion threads.
>>>>>>>>>>> We have a minimum of 2 commiters required for every patch. Should we not trust them to update nodetool, the virtual tables or other things on their own?
>>>>>>>>>>>
>>>>>>>>>>> There is already multiple existing ways to track changes in specific code areas. I am personaly tracking the areas in which I am the most involved this way and I know that a lot of people do the same.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> To be transparent, It is not clear to me what the underlying issue is? Do we have some specific cases that illustrate the underlying problem? Thrift and JMX are from a different time in my opinion.
>>>>>>>>>>>
>>>>>>>>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a écrit :
>>>>>>>>>>>> +1 to moving that into it's own section outside the coding style page.
>>>>>>>>>>>>
>>>>>>>>>>>> Dinesh I also thought in terms of backward compatibility here. But notice the discussion is about _any change_ to the API such as adding new CQL functions. Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also? I wonder if we're talking ourselves into opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>>>>>>>>
>>>>>>>>>>>> I wonder, you guys know the code better, if 'public APIs' could be matched to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send an email when changes are detected on them. Overkill? bad idea? :thinking:...
>>>>>>>>>>>>
>>>>>>>>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>>>>>>>>> We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
>>>>>>>>>>>>>
>>>>>>>>>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
>>>>>>>>>>>>>
>>>>>>>>>>>>> The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> Public APIs
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> My .02:
>>>>>>>>>>>>>>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>>>>>>>>>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> We've learned that API's are *really really hard* to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> ~Josh
>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benedict <be...@apache.org>.
My view is simply that API discussion should be undertaken in a broader forum than Jira. The lower the bar to participation on this stuff the better, as it isn’t deeply technical and we have lots of lurkers here that have relevant experience and knowledge that can chime in with valuable feedback if given the chance. The transaction syntax thread demonstrated this with participants we do not often see.
Jira is exceptionally noisy, and most discussion is not particularly important for broad consumption - implementation decisions can always be revisited, and are anyway fine to be suboptimal. So quite rationally most folk do not pay attention.
We want their input for this stuff though. So, yes, I think we should ideally keep API discussions to this list, preferably exclusively (modulo preparatory discussions), as that retains a high signal:noise funnel of information for people to subscribe to and participate in at low cost.
Links to a list of API topics in the status email just doesn’t serve this purpose.
> On 5 Dec 2022, at 16:15, Josh McKenzie <jm...@apache.org> wrote:
>
>
>>
>> can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report?
>
>> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
> My understanding of Ekaterina's suggestions it that I add a [Pending API Changes] section to the email thread every 2-3 weeks w/everything that's opened within that time frame with that tag. Batch processing by interested parties periodically rather than bulk batch processing at the end of a release cycle.
>
> I'm happy to take that on and I think that model could work. I'm also happy with a DISCUSS thread once a week on some pending API change someone has in flight; to me that doesn't seem like too big a burden, especially if a solid majority of them are lazy consensus noops.
>
>> Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also?
> I'm an emphatic "Yes" on this. I've had to use some poorly fit exception types in the past because of legacy coupling / commitment with the existing API's that make it harder both for us to work on things in the codebase and harder for our users to understand what we're trying to communicate with them. Further, users have splunk queries and other automated parsing set up to check logs for specific exceptions and warning texts; changing those things breaks an unknown number of downstream consumers and creates toil, or worse, introduces outages, for users.
>
>> On Mon, Dec 5, 2022, at 10:34 AM, Andrés de la Peña wrote:
>> This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>>
>> That after the fact review approach doesn't seem very dependant on whether we have a DISCUSS thread for every change or not, since those supervision scans will probably still happen. After all anyone can ask for modifications on anything at any moment, previously agreed or not. For example, the CEP for guardrails was publicly discussed, voted, approved, reviewed and committed with nested config and a global enable flag, and still we had to revert those two things shortly after commit.
>>
>> On Mon, 5 Dec 2022 at 15:12, Ekaterina Dimitrova <e....@gmail.com> wrote:
>> “ I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.”
>> Just to clarify, I do not suggest to use the status mail to respond with concerns. But more like - having a link to the filter in the bi-weekly report and then everyone can open it and check the list of tickets and comment directly on the tickets or open a thread if they think the issue deserves one.
>> Same as having link to the tickets that are blockers or tickets that need reviewers. Whoever wants will have an easy way to get to those and take whatever actions they want.
>>
>> On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
>>
>> Perhaps you misunderstand my concern? I think these decisions need broader input, not just my input.
>>
>> Are you therefore asking why I do not monitor these topics and propose DISCUSS threads based on activities others are undertaking? This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>>
>> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
>>
>>
>>
>>>> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>>>
>>
>>> Benedict, I am confused. If you are so much concerned about virtual tables or CQL why do you not track those components changes directly? People usually label them correctly I believe. Like that you would be able to provide feedback straight away rather than after the fact. It would be a win for everybody, no?
>>>
>>> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com> a écrit :
>>> Quick idea - can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report? In the meantime if there are big changes that people consider they need a DISCUSS thread for they can always open one? I will be happy to help with the mentioned filter/report.
>>> Also +1 on having Contributing doc with broader discussion and directions around API
>>>
>>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>>
>>> I would be fine with a formal API change review period prior to release, but if we go that route people should expect to have to revisit work they completed a while back, and there should be no presumption that decisions taken without a DISCUSS thread should be preferred to alternative suggestions - and we should have a clear policy of reverting any work if it is not revisited based on the outcome of any discussion, since seeking broader input earlier was always an option. I expect this approach could lead to frustration, but it might actually be a better system than separate DISCUSS threads as the changes can be considered holistically.
>>>
>>> The idea that a DISCUSS thread for each change would be burdensome however is I think mistaken. Even if 70 were the true figure, it would have been around one per week, and they could easily have been batched. I’d also be fine with white listing some changes (eg JMX and warning messages) - but definitely not virtual tables or CQL. These APIs develop strong user dependencies, and are very hard to change.
>>>
>>> We should not restrict input on our main user experiences to the handful of people with time to closely monitor Jira, most of whom are not even users of Cassandra. We should be seeking the broadest visibility, including casual observers and non-contributors.
>>>
>>>
>>>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>>
>>>
>>>> It feels bit of overkill to me to require addition of any new virtual tables/JMX/configuration/knob to go through a discuss thread. If this would require 70 threads for the previous release I think this would easily become spammy and counter-productive.
>>>>
>>>> I think the burden should be on the maintainer to keep up with changes being added to the database and chime in any areas it feel responsible for, as it has been the case and has worked relatively well.
>>>>
>>>> I think it makes sense to look into improving visibility of API changes, so people can more easily review a summary of API changes versus reading through the whole changelog (perhaps we need a summarized API change log?).
>>>>
>>>> It would also help to have more explicit guidelines on what kinds of API changes are riskier and might require additional visibility via a DISCUSS thread.
>>>>
>>>> Also, would it make sense to introduce a new API review stage during release validation, and agree to revert/update any API changes that may be controversial that were not caught during normal review?
>>>>
>>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
>>>> Indeed that contribution policy should be clearer and not be on a page titled code style, thanks for briging that up.
>>>>
>>>> If we consider all those things APIs, and additions are also considered changes that require a DISCUSS thread, it turns out that almost any not-bugfix ticket would require a mail list thread. In fact, if one goes through CHANGES.txt it's easy to see that most entries would have required a DISCUSS thread.
>>>>
>>>> I think that such a strict policy would only make us lose agility and increase the burden of almost any contribution. After all, it's not that changes without a DISCUSS thread happen in secret. Changes are publicly visible on their tickets, those tickets are notified on Slack so anyone can jump into the ticket discussions and set themselves as reviewers, and reviewers can ask for DISCUSS threads whenever they think more opinions or broader consensus are needed.
>>>>
>>>> Also, a previous DISCUSS thread is not going to impede that any changes are going to be questioned later. We have seen changes that are proposed, discussed and approved as CEPs, reviewed for weeks or months, and finally committed, and still they are questioned shortly after that cycle, and asked to be changed or discussed again. I don't think that an avalanche of DISCUSS threads is going to improve that, since usually the problem is that people don't have the time for deeply looking into the changes when they are happening. I doubt that more notification channels are going to improve that.
>>>>
>>>> Of course I'm not saying that there should never DISCUSS threads before starting a change. Probably we can all agree that major changes and things that break compatibility would need previous discussion.
>>>>
>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>> Thanks for opening this thread Josh,
>>>>
>>>> It seems perfectly normal to me that for important changes or questions we raise some discussion to the mailing list.
>>>>
>>>> My understanding of the current proposal implies that for the 4.1 release we should have had to raise over 70 discussion threads.
>>>> We have a minimum of 2 commiters required for every patch. Should we not trust them to update nodetool, the virtual tables or other things on their own?
>>>>
>>>> There is already multiple existing ways to track changes in specific code areas. I am personaly tracking the areas in which I am the most involved this way and I know that a lot of people do the same.
>>>>
>>>>
>>>>
>>>> To be transparent, It is not clear to me what the underlying issue is? Do we have some specific cases that illustrate the underlying problem? Thrift and JMX are from a different time in my opinion.
>>>>
>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a écrit :
>>>> +1 to moving that into it's own section outside the coding style page.
>>>>
>>>> Dinesh I also thought in terms of backward compatibility here. But notice the discussion is about _any change_ to the API such as adding new CQL functions. Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also? I wonder if we're talking ourselves into opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>
>>>> I wonder, you guys know the code better, if 'public APIs' could be matched to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send an email when changes are detected on them. Overkill? bad idea? :thinking:...
>>>>
>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>> We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
>>>>>
>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
>>>>>
>>>>> The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
>>>>>
>>>>>
>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>
>>>>>> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>>>>>>
>>>>>> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>>>>>>
>>>>>> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>>>>>>
>>>>>> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>>>>>>
>>>>>> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>>>>>>
>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>
>>>>>>>
>>>>>>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>
>>>>>>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>>>>>>
>>>>>>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>>>>>>>
>>>>>>>> Public APIs
>>>>>>>>
>>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>>
>>>>>>>
>>>>>>> My .02:
>>>>>>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>>>>>>
>>>>>>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>>>>>>
>>>>>>> We've learned that API's are really really hard to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>>>>>>
>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>>>>>>
>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>
>>>>>>> ~Josh
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benjamin Lerer <bl...@apache.org>.
>
> Are you therefore asking why I do not monitor these topics and propose
> DISCUSS threads based on activities others are undertaking? This doesn’t
> seem like the right approach to me, but if we do not come to some policy
> approach here, I will try to schedule some time each quarter to scan for
> topics I think should have had a DISCUSS thread, and open them up for
> discussion.
No. :-) Sorry, I realize that we do not have the same perspective at all.
I am following the ticket changes that are happening at a high level. If I
see some changes I am concerned about, I just comment on the ticket even if
it is simply asking to raise the discussion at the community level. Over
the last 2 years it happened only once. The rest of the time I simply
provided inputs to the ticket. People took them into consideration and it
was enough for me.
Le lun. 5 déc. 2022 à 17:14, Josh McKenzie <jm...@apache.org> a écrit :
> can we add a label in Jira API or something like that and then Josh can
> filter those in the bi-weekly report?
>
>
> I do not personally think the project status thread is the right venue
> for this, though a periodic dedicated “API Changes” thread might not be a
> bad approach.
>
> My understanding of Ekaterina's suggestions it that I add a [Pending API
> Changes] section to the email thread every 2-3 weeks w/everything that's
> opened within that time frame with that tag. Batch processing by interested
> parties periodically rather than bulk batch processing at the end of a
> release cycle.
>
> I'm happy to take that on and I think that model could work. I'm also
> happy with a DISCUSS thread once a week on some pending API change someone
> has in flight; to me that doesn't seem like too big a burden, especially if
> a solid majority of them are lazy consensus noops.
>
> Would adding or changing an exception type or a user warning qualify for a
> DISCUSS thread also?
>
> I'm an emphatic "Yes" on this. I've had to use some poorly fit exception
> types in the past because of legacy coupling / commitment with the existing
> API's that make it harder both for us to work on things in the codebase and
> harder for our users to understand what we're trying to communicate with
> them. Further, users have splunk queries and other automated parsing set up
> to check logs for specific exceptions and warning texts; changing those
> things breaks an unknown number of downstream consumers and creates toil,
> or worse, introduces outages, for users.
>
> On Mon, Dec 5, 2022, at 10:34 AM, Andrés de la Peña wrote:
>
> This doesn’t seem like the right approach to me, but if we do not come to
> some policy approach here, I will try to schedule some time each quarter to
> scan for topics I think should have had a DISCUSS thread, and open them up
> for discussion.
>
>
> That after the fact review approach doesn't seem very dependant on whether
> we have a DISCUSS thread for every change or not, since those supervision
> scans will probably still happen. After all anyone can ask for
> modifications on anything at any moment, previously agreed or not. For
> example, the CEP for guardrails was publicly discussed, voted, approved,
> reviewed and committed with nested config and a global enable flag, and
> still we had to revert those two things shortly after commit.
>
> On Mon, 5 Dec 2022 at 15:12, Ekaterina Dimitrova <e....@gmail.com>
> wrote:
>
> “ I do not personally think the project status thread is the right venue
> for this, though a periodic dedicated “API Changes” thread might not be a
> bad approach.”
> Just to clarify, I do not suggest to use the status mail to respond with
> concerns. But more like - having a link to the filter in the bi-weekly
> report and then everyone can open it and check the list of tickets and
> comment directly on the tickets or open a thread if they think the issue
> deserves one.
> Same as having link to the tickets that are blockers or tickets that need
> reviewers. Whoever wants will have an easy way to get to those and take
> whatever actions they want.
>
> On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
>
>
> Perhaps you misunderstand my concern? I think these decisions need broader
> input, not just my input.
>
> Are you therefore asking why I do not monitor these topics and propose
> DISCUSS threads based on activities others are undertaking? This doesn’t
> seem like the right approach to me, but if we do not come to some policy
> approach here, I will try to schedule some time each quarter to scan for
> topics I think should have had a DISCUSS thread, and open them up for
> discussion.
>
> I do not personally think the project status thread is the right venue for
> this, though a periodic dedicated “API Changes” thread might not be a bad
> approach.
>
>
>
> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>
>
>
> Benedict, I am confused. If you are so much concerned about virtual tables
> or CQL why do you not track those components changes directly? People
> usually label them correctly I believe. Like that you would be able to
> provide feedback straight away rather than after the fact. It would be a
> win for everybody, no?
>
> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com>
> a écrit :
>
> Quick idea - can we add a label in Jira API or something like that and
> then Josh can filter those in the bi-weekly report? In the meantime if
> there are big changes that people consider they need a DISCUSS thread for
> they can always open one? I will be happy to help with the mentioned
> filter/report.
> Also +1 on having Contributing doc with broader discussion and directions
> around API
>
> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>
>
> I would be fine with a formal API change review period prior to release,
> but if we go that route people should expect to have to revisit work they
> completed a while back, and there should be no presumption that decisions
> taken without a DISCUSS thread should be preferred to alternative
> suggestions - and we should have a clear policy of reverting any work if it
> is not revisited based on the outcome of any discussion, since seeking
> broader input earlier was always an option. I expect this approach could
> lead to frustration, but it might actually be a better system than separate
> DISCUSS threads as the changes can be considered holistically.
>
> The idea that a DISCUSS thread for each change would be burdensome however
> is I think mistaken. Even if 70 were the true figure, it would have been
> around one per week, and they could easily have been batched. I’d also be
> fine with white listing some changes (eg JMX and warning messages) - but
> definitely not virtual tables or CQL. These APIs develop strong user
> dependencies, and are very hard to change.
>
> We should not restrict input on our main user experiences to the handful
> of people with time to closely monitor Jira, most of whom are not even
> users of Cassandra. We should be seeking the broadest visibility, including
> casual observers and non-contributors.
>
>
> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>
>
>
> It feels bit of overkill to me to require addition of any new virtual
> tables/JMX/configuration/knob to go through a discuss thread. If this would
> require 70 threads for the previous release I think this would easily
> become spammy and counter-productive.
>
> I think the burden should be on the maintainer to keep up with changes
> being added to the database and chime in any areas it feel responsible for,
> as it has been the case and has worked relatively well.
>
> I think it makes sense to look into improving visibility of API changes,
> so people can more easily review a summary of API changes versus reading
> through the whole changelog (perhaps we need a summarized API change log?).
>
> It would also help to have more explicit guidelines on what kinds of API
> changes are riskier and might require additional visibility via a DISCUSS
> thread.
>
> Also, would it make sense to introduce a new API review stage during
> release validation, and agree to revert/update any API changes that may be
> controversial that were not caught during normal review?
>
> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org>
> wrote:
>
> Indeed that contribution policy should be clearer and not be on a page
> titled code style, thanks for briging that up.
>
> If we consider all those things APIs, and additions are also considered
> changes that require a DISCUSS thread, it turns out that almost any
> not-bugfix ticket would require a mail list thread. In fact, if one goes
> through CHANGES.txt it's easy to see that most entries would have required
> a DISCUSS thread.
>
> I think that such a strict policy would only make us lose agility and
> increase the burden of almost any contribution. After all, it's not that
> changes without a DISCUSS thread happen in secret. Changes are publicly
> visible on their tickets, those tickets are notified on Slack so anyone can
> jump into the ticket discussions and set themselves as reviewers, and
> reviewers can ask for DISCUSS threads whenever they think more opinions or
> broader consensus are needed.
>
> Also, a previous DISCUSS thread is not going to impede that any changes
> are going to be questioned later. We have seen changes that are proposed,
> discussed and approved as CEPs, reviewed for weeks or months, and finally
> committed, and still they are questioned shortly after that cycle, and
> asked to be changed or discussed again. I don't think that an avalanche of
> DISCUSS threads is going to improve that, since usually the problem is that
> people don't have the time for deeply looking into the changes when they
> are happening. I doubt that more notification channels are going to improve
> that.
>
> Of course I'm not saying that there should never DISCUSS threads before
> starting a change. Probably we can all agree that major changes and things
> that break compatibility would need previous discussion.
>
> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>
> Thanks for opening this thread Josh,
>
> It seems perfectly normal to me that for important changes or questions we
> raise some discussion to the mailing list.
>
> My understanding of the current proposal implies that for the 4.1 release
> we should have had to raise over 70 discussion threads.
> We have a minimum of 2 commiters required for every patch. Should we not
> trust them to update nodetool, the virtual tables or other things on their
> own?
>
> There is already multiple existing ways to track changes in specific code
> areas. I am personaly tracking the areas in which I am the most involved
> this way and I know that a lot of people do the same.
>
>
>
> To be transparent, It is not clear to me what the underlying issue is? Do
> we have some specific cases that illustrate the underlying problem? Thrift
> and JMX are from a different time in my opinion.
>
> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a
> écrit :
>
> +1 to moving that into it's own section outside the coding style page.
>
> Dinesh I also thought in terms of backward compatibility here. But notice
> the discussion is about _any change_ to the API such as adding new CQL
> functions. Would adding or changing an exception type or a user warning
> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
> opening a DISCUSS for almost every ticket and sthg easy to miss.
>
> I wonder, you guys know the code better, if 'public APIs' could be matched
> to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send
> an email when changes are detected on them. Overkill? bad idea?
> :thinking:...
> On 4/12/22 1:14, Dinesh Joshi wrote:
>
> We should also very clearly list out what is considered a public API. The
> current statement that we have is insufficient:
>
> public APIs, including CQL, virtual tables, JMX, yaml, system
> properties, etc.
>
>
> The guidance on treatment of public APIs should also move out of "Code
> Style" page as it isn't strictly related to code style. Backward
> compatibility of public APIs is a best practice & project policy.
>
>
> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>
> I think some of that text also got garbled by mixing up how you approach
> internal APIs and external APIs. We should probably clarify that there are
> different burdens for each. Which is all my fault as the formulator. I
> remember it being much clearer in my head.
>
> My view is the same as yours Josh. Evolving the database’s public APIs is
> something that needs community consensus. The more visibility these
> decisions get, the better the final outcome (usually). Even small API
> changes need to be carefully considered to ensure the API evolves
> coherently, and this is particularly true for something as complex and
> central as CQL.
>
> A DISCUSS thread is a good forcing function to think about what you’re
> trying to achieve and why, and to provide others a chance to spot potential
> flaws, alternatives and interactions with work you may not be aware of.
>
> It would be nice if there were an easy rubric for whether something needs
> feedback, but I don’t think there is. One person’s obvious change may be
> another’s obvious problem. So I think any decision that binds the project
> going forwards should have a lazy consensus DISCUSS thread at least.
>
> I don’t think it needs to be burdensome though - trivial API changes could
> begin while the DISCUSS thread is underway, expecting they usually won’t
> raise a murmur.
>
> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>
>
> Came up this morning / afternoon in dev slack:
> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>
> The gist of it: we're lacking clarity on whether the expectation on the
> project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification
> or only on modifications where the author feels they are adjusting a
> paradigm / strategy for an API.
>
> The code style section on Public APIs is actually a little unclear:
> https://cassandra.apache.org/_/development/code_style.html
>
> Public APIs
>
> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>
>
> My .02:
> 1. We should rename that page to a "code contribution guide" as discussed
> on the slack thread
> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
> vtables, .java interfaces targeting user extension, etc) should hit the dev
> ML w/a [DISCUSS] thread.
>
> This takes the burden of trying to determine if a change is consistent
> w/existing strategy or not etc. off the author in isolation and allows devs
> to work concurrently on API changes w/out risk of someone else working on
> something that may inform their work or vice versa.
>
> We've learned that API's are *really really hard* to deprecate,
> disruptive to our users when we change or remove them, and can cause
> serious pain and ecosystem fragmentation when changed. See: Thrift, current
> discussions about JMX, etc. They're the definition of a "one-way-door"
> decision and represent a long-term maintenance burden commitment from the
> project.
>
> Lastly, I'd expect the vast majority of these discuss threads to be quick
> consensus checks resolved via lazy consensus or after some slight
> discussion; ideally this wouldn't represent a huge burden of coordination
> on folks working on changes.
>
> So that's 1 opinion. What other opinions are out there?
>
> ~Josh
>
>
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Josh McKenzie <jm...@apache.org>.
> can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report?
> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
My understanding of Ekaterina's suggestions it that I add a [Pending API Changes] section to the email thread every 2-3 weeks w/everything that's opened within that time frame with that tag. Batch processing by interested parties periodically rather than bulk batch processing at the end of a release cycle.
I'm happy to take that on and I think that model could work. I'm also happy with a DISCUSS thread once a week on some pending API change someone has in flight; to me that doesn't seem like too big a burden, especially if a solid majority of them are lazy consensus noops.
> Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also?
I'm an emphatic "Yes" on this. I've had to use some poorly fit exception types in the past because of legacy coupling / commitment with the existing API's that make it harder both for us to work on things in the codebase and harder for our users to understand what we're trying to communicate with them. Further, users have splunk queries and other automated parsing set up to check logs for specific exceptions and warning texts; changing those things breaks an unknown number of downstream consumers and creates toil, or worse, introduces outages, for users.
On Mon, Dec 5, 2022, at 10:34 AM, Andrés de la Peña wrote:
>> This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>
> That after the fact review approach doesn't seem very dependant on whether we have a DISCUSS thread for every change or not, since those supervision scans will probably still happen. After all anyone can ask for modifications on anything at any moment, previously agreed or not. For example, the CEP for guardrails was publicly discussed, voted, approved, reviewed and committed with nested config and a global enable flag, and still we had to revert those two things shortly after commit.
>
> On Mon, 5 Dec 2022 at 15:12, Ekaterina Dimitrova <e....@gmail.com> wrote:
>> “ I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.”
>> Just to clarify, I do not suggest to use the status mail to respond with concerns. But more like - having a link to the filter in the bi-weekly report and then everyone can open it and check the list of tickets and comment directly on the tickets or open a thread if they think the issue deserves one.
>> Same as having link to the tickets that are blockers or tickets that need reviewers. Whoever wants will have an easy way to get to those and take whatever actions they want.
>>
>> On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
>>>
>>> Perhaps you misunderstand my concern? I think these decisions need broader input, not just my input.
>>>
>>> Are you therefore asking why I do not monitor these topics and propose DISCUSS threads based on activities others are undertaking? This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
>>>
>>> I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
>>>
>>>
>>>
>>>> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>>>>
>>>> Benedict, I am confused. If you are so much concerned about virtual tables or CQL why do you not track those components changes directly? People usually label them correctly I believe. Like that you would be able to provide feedback straight away rather than after the fact. It would be a win for everybody, no?
>>>>
>>>> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com> a écrit :
>>>>> Quick idea - can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report? In the meantime if there are big changes that people consider they need a DISCUSS thread for they can always open one? I will be happy to help with the mentioned filter/report.
>>>>> Also +1 on having Contributing doc with broader discussion and directions around API
>>>>>
>>>>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>>>>>
>>>>>> I would be fine with a formal API change review period prior to release, but if we go that route people should expect to have to revisit work they completed a while back, and there should be no presumption that decisions taken without a DISCUSS thread should be preferred to alternative suggestions - and we should have a clear policy of reverting any work if it is not revisited based on the outcome of any discussion, since seeking broader input earlier was always an option. I expect this approach could lead to frustration, but it might actually be a better system than separate DISCUSS threads as the changes can be considered holistically.
>>>>>>
>>>>>> The idea that a DISCUSS thread for each change would be burdensome however is I think mistaken. Even if 70 were the true figure, it would have been around one per week, and they could easily have been batched. I’d also be fine with white listing some changes (eg JMX and warning messages) - but definitely not virtual tables or CQL. These APIs develop strong user dependencies, and are very hard to change.
>>>>>>
>>>>>> We should not restrict input on our main user experiences to the handful of people with time to closely monitor Jira, most of whom are not even users of Cassandra. We should be seeking the broadest visibility, including casual observers and non-contributors.
>>>>>>
>>>>>>
>>>>>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>>>>>
>>>>>>> It feels bit of overkill to me to require addition of any new virtual tables/JMX/configuration/knob to go through a discuss thread. If this would require 70 threads for the previous release I think this would easily become spammy and counter-productive.
>>>>>>>
>>>>>>> I think the burden should be on the maintainer to keep up with changes being added to the database and chime in any areas it feel responsible for, as it has been the case and has worked relatively well.
>>>>>>>
>>>>>>> I think it makes sense to look into improving visibility of API changes, so people can more easily review a summary of API changes versus reading through the whole changelog (perhaps we need a summarized API change log?).
>>>>>>>
>>>>>>> It would also help to have more explicit guidelines on what kinds of API changes are riskier and might require additional visibility via a DISCUSS thread.
>>>>>>>
>>>>>>> Also, would it make sense to introduce a new API review stage during release validation, and agree to revert/update any API changes that may be controversial that were not caught during normal review?
>>>>>>>
>>>>>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
>>>>>>>> Indeed that contribution policy should be clearer and not be on a page titled code style, thanks for briging that up.
>>>>>>>>
>>>>>>>> If we consider all those things APIs, and additions are also considered changes that require a DISCUSS thread, it turns out that almost any not-bugfix ticket would require a mail list thread. In fact, if one goes through CHANGES.txt it's easy to see that most entries would have required a DISCUSS thread.
>>>>>>>>
>>>>>>>> I think that such a strict policy would only make us lose agility and increase the burden of almost any contribution. After all, it's not that changes without a DISCUSS thread happen in secret. Changes are publicly visible on their tickets, those tickets are notified on Slack so anyone can jump into the ticket discussions and set themselves as reviewers, and reviewers can ask for DISCUSS threads whenever they think more opinions or broader consensus are needed.
>>>>>>>>
>>>>>>>> Also, a previous DISCUSS thread is not going to impede that any changes are going to be questioned later. We have seen changes that are proposed, discussed and approved as CEPs, reviewed for weeks or months, and finally committed, and still they are questioned shortly after that cycle, and asked to be changed or discussed again. I don't think that an avalanche of DISCUSS threads is going to improve that, since usually the problem is that people don't have the time for deeply looking into the changes when they are happening. I doubt that more notification channels are going to improve that.
>>>>>>>>
>>>>>>>> Of course I'm not saying that there should never DISCUSS threads before starting a change. Probably we can all agree that major changes and things that break compatibility would need previous discussion.
>>>>>>>>
>>>>>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>>>>>>> Thanks for opening this thread Josh,
>>>>>>>>>
>>>>>>>>> It seems perfectly normal to me that for important changes or questions we raise some discussion to the mailing list.
>>>>>>>>>
>>>>>>>>> My understanding of the current proposal implies that for the 4.1 release we should have had to raise over 70 discussion threads.
>>>>>>>>> We have a minimum of 2 commiters required for every patch. Should we not trust them to update nodetool, the virtual tables or other things on their own?
>>>>>>>>>
>>>>>>>>> There is already multiple existing ways to track changes in specific code areas. I am personaly tracking the areas in which I am the most involved this way and I know that a lot of people do the same.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> To be transparent, It is not clear to me what the underlying issue is? Do we have some specific cases that illustrate the underlying problem? Thrift and JMX are from a different time in my opinion.
>>>>>>>>>
>>>>>>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a écrit :
>>>>>>>>>> +1 to moving that into it's own section outside the coding style page.
>>>>>>>>>>
>>>>>>>>>> Dinesh I also thought in terms of backward compatibility here. But notice the discussion is about _any change_ to the API such as adding new CQL functions. Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also? I wonder if we're talking ourselves into opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>>>>>>
>>>>>>>>>> I wonder, you guys know the code better, if 'public APIs' could be matched to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send an email when changes are detected on them. Overkill? bad idea? :thinking:...
>>>>>>>>>>
>>>>>>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>>>>>>> We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
>>>>>>>>>>>
>>>>>>>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
>>>>>>>>>>>
>>>>>>>>>>> The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>>>>>>>>>>>>
>>>>>>>>>>>> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>>>>>>>>>>>>
>>>>>>>>>>>> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>>>>>>>>>>>>
>>>>>>>>>>>> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>>>>>>>>>>>>
>>>>>>>>>>>> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>>>>>>>>>>>>
>>>>>>>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>>>>>>>
>>>>>>>>>>>>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>>>>>>>>>>>>
>>>>>>>>>>>>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>>>>>>>>>>>>>
>>>>>>>>>>>>>> Public APIs
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> My .02:
>>>>>>>>>>>>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>>>>>>>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>>>>>>>>>>>>
>>>>>>>>>>>>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>>>>>>>>>>>>
>>>>>>>>>>>>> We've learned that API's are *really really hard* to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>>>>>>>>>>>>
>>>>>>>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>>>>>>>>>>>>
>>>>>>>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>>>>>>>
>>>>>>>>>>>>> ~Josh
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Andrés de la Peña <ad...@apache.org>.
>
> This doesn’t seem like the right approach to me, but if we do not come to
> some policy approach here, I will try to schedule some time each quarter to
> scan for topics I think should have had a DISCUSS thread, and open them up
> for discussion.
That after the fact review approach doesn't seem very dependant on whether
we have a DISCUSS thread for every change or not, since those supervision
scans will probably still happen. After all anyone can ask for
modifications on anything at any moment, previously agreed or not. For
example, the CEP for guardrails was publicly discussed, voted, approved,
reviewed and committed with nested config and a global enable flag, and
still we had to revert those two things shortly after commit.
On Mon, 5 Dec 2022 at 15:12, Ekaterina Dimitrova <e....@gmail.com>
wrote:
> “ I do not personally think the project status thread is the right venue
> for this, though a periodic dedicated “API Changes” thread might not be a
> bad approach.”
> Just to clarify, I do not suggest to use the status mail to respond with
> concerns. But more like - having a link to the filter in the bi-weekly
> report and then everyone can open it and check the list of tickets and
> comment directly on the tickets or open a thread if they think the issue
> deserves one.
> Same as having link to the tickets that are blockers or tickets that need
> reviewers. Whoever wants will have an easy way to get to those and take
> whatever actions they want.
>
> On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
>
>> Perhaps you misunderstand my concern? I think these decisions need
>> broader input, not just my input.
>>
>> Are you therefore asking why I do not monitor these topics and propose
>> DISCUSS threads based on activities others are undertaking? This doesn’t
>> seem like the right approach to me, but if we do not come to some policy
>> approach here, I will try to schedule some time each quarter to scan for
>> topics I think should have had a DISCUSS thread, and open them up for
>> discussion.
>>
>> I do not personally think the project status thread is the right venue
>> for this, though a periodic dedicated “API Changes” thread might not be a
>> bad approach.
>>
>>
>> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>>
>>
>>
>> Benedict, I am confused. If you are so much concerned about virtual
>> tables or CQL why do you not track those components changes directly?
>> People usually label them correctly I believe. Like that you would be able
>> to provide feedback straight away rather than after the fact. It would be a
>> win for everybody, no?
>>
>> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com>
>> a écrit :
>>
>>> Quick idea - can we add a label in Jira API or something like that and
>>> then Josh can filter those in the bi-weekly report? In the meantime if
>>> there are big changes that people consider they need a DISCUSS thread for
>>> they can always open one? I will be happy to help with the mentioned
>>> filter/report.
>>> Also +1 on having Contributing doc with broader discussion and
>>> directions around API
>>>
>>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>>
>>>> I would be fine with a formal API change review period prior to
>>>> release, but if we go that route people should expect to have to revisit
>>>> work they completed a while back, and there should be no presumption that
>>>> decisions taken without a DISCUSS thread should be preferred to alternative
>>>> suggestions - and we should have a clear policy of reverting any work if it
>>>> is not revisited based on the outcome of any discussion, since seeking
>>>> broader input earlier was always an option. I expect this approach could
>>>> lead to frustration, but it might actually be a better system than separate
>>>> DISCUSS threads as the changes can be considered holistically.
>>>>
>>>> The idea that a DISCUSS thread for each change would be burdensome
>>>> however is I think mistaken. Even if 70 were the true figure, it would have
>>>> been around one per week, and they could easily have been batched. I’d also
>>>> be fine with white listing some changes (eg JMX and warning messages) - but
>>>> definitely not virtual tables or CQL. These APIs develop strong user
>>>> dependencies, and are very hard to change.
>>>>
>>>> We should not restrict input on our main user experiences to the
>>>> handful of people with time to closely monitor Jira, most of whom are not
>>>> even users of Cassandra. We should be seeking the broadest visibility,
>>>> including casual observers and non-contributors.
>>>>
>>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>>
>>>>
>>>>
>>>> It feels bit of overkill to me to require addition of any new virtual
>>>> tables/JMX/configuration/knob to go through a discuss thread. If this would
>>>> require 70 threads for the previous release I think this would easily
>>>> become spammy and counter-productive.
>>>>
>>>> I think the burden should be on the maintainer to keep up with changes
>>>> being added to the database and chime in any areas it feel responsible for,
>>>> as it has been the case and has worked relatively well.
>>>>
>>>> I think it makes sense to look into improving visibility of API
>>>> changes, so people can more easily review a summary of API changes versus
>>>> reading through the whole changelog (perhaps we need a summarized API
>>>> change log?).
>>>>
>>>> It would also help to have more explicit guidelines on what kinds of
>>>> API changes are riskier and might require additional visibility via a
>>>> DISCUSS thread.
>>>>
>>>> Also, would it make sense to introduce a new API review stage during
>>>> release validation, and agree to revert/update any API changes that may be
>>>> controversial that were not caught during normal review?
>>>>
>>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org>
>>>> wrote:
>>>>
>>>>> Indeed that contribution policy should be clearer and not be on a page
>>>>> titled code style, thanks for briging that up.
>>>>>
>>>>> If we consider all those things APIs, and additions are also
>>>>> considered changes that require a DISCUSS thread, it turns out that almost
>>>>> any not-bugfix ticket would require a mail list thread. In fact, if one
>>>>> goes through CHANGES.txt it's easy to see that most entries would have
>>>>> required a DISCUSS thread.
>>>>>
>>>>> I think that such a strict policy would only make us lose agility and
>>>>> increase the burden of almost any contribution. After all, it's not that
>>>>> changes without a DISCUSS thread happen in secret. Changes are publicly
>>>>> visible on their tickets, those tickets are notified on Slack so anyone can
>>>>> jump into the ticket discussions and set themselves as reviewers, and
>>>>> reviewers can ask for DISCUSS threads whenever they think more opinions or
>>>>> broader consensus are needed.
>>>>>
>>>>> Also, a previous DISCUSS thread is not going to impede that any
>>>>> changes are going to be questioned later. We have seen changes that are
>>>>> proposed, discussed and approved as CEPs, reviewed for weeks or months, and
>>>>> finally committed, and still they are questioned shortly after that cycle,
>>>>> and asked to be changed or discussed again. I don't think that an avalanche
>>>>> of DISCUSS threads is going to improve that, since usually the problem is
>>>>> that people don't have the time for deeply looking into the changes when
>>>>> they are happening. I doubt that more notification channels are going to
>>>>> improve that.
>>>>>
>>>>> Of course I'm not saying that there should never DISCUSS threads
>>>>> before starting a change. Probably we can all agree that major changes and
>>>>> things that break compatibility would need previous discussion.
>>>>>
>>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>>>
>>>>>> Thanks for opening this thread Josh,
>>>>>>
>>>>>> It seems perfectly normal to me that for important changes or
>>>>>> questions we raise some discussion to the mailing list.
>>>>>>
>>>>>> My understanding of the current proposal implies that for the 4.1
>>>>>> release we should have had to raise over 70 discussion threads.
>>>>>> We have a minimum of 2 commiters required for every patch. Should we
>>>>>> not trust them to update nodetool, the virtual tables or other things on
>>>>>> their own?
>>>>>>
>>>>>> There is already multiple existing ways to track changes in specific
>>>>>> code areas. I am personaly tracking the areas in which I am the most
>>>>>> involved this way and I know that a lot of people do the same.
>>>>>>
>>>>>> To be transparent, It is not clear to me what the underlying issue
>>>>>> is? Do we have some specific cases that illustrate the underlying problem?
>>>>>> Thrift and JMX are from a different time in my opinion.
>>>>>>
>>>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <
>>>>>> berenguerblasi@gmail.com> a écrit :
>>>>>>
>>>>>>> +1 to moving that into it's own section outside the coding style
>>>>>>> page.
>>>>>>>
>>>>>>> Dinesh I also thought in terms of backward compatibility here. But
>>>>>>> notice the discussion is about _any change_ to the API such as adding new
>>>>>>> CQL functions. Would adding or changing an exception type or a user warning
>>>>>>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>>>>>>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>>>
>>>>>>> I wonder, you guys know the code better, if 'public APIs' could be
>>>>>>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>>>>>>> jenkins send an email when changes are detected on them. Overkill? bad
>>>>>>> idea? :thinking:...
>>>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>>>
>>>>>>> We should also very clearly list out what is considered a public
>>>>>>> API. The current statement that we have is insufficient:
>>>>>>>
>>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system
>>>>>>> properties, etc.
>>>>>>>
>>>>>>>
>>>>>>> The guidance on treatment of public APIs should also move out of
>>>>>>> "Code Style" page as it isn't strictly related to code style. Backward
>>>>>>> compatibility of public APIs is a best practice & project policy.
>>>>>>>
>>>>>>>
>>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>>
>>>>>>> I think some of that text also got garbled by mixing up how you
>>>>>>> approach internal APIs and external APIs. We should probably clarify that
>>>>>>> there are different burdens for each. Which is all my fault as the
>>>>>>> formulator. I remember it being much clearer in my head.
>>>>>>>
>>>>>>> My view is the same as yours Josh. Evolving the database’s public
>>>>>>> APIs is something that needs community consensus. The more visibility these
>>>>>>> decisions get, the better the final outcome (usually). Even small API
>>>>>>> changes need to be carefully considered to ensure the API evolves
>>>>>>> coherently, and this is particularly true for something as complex and
>>>>>>> central as CQL.
>>>>>>>
>>>>>>> A DISCUSS thread is a good forcing function to think about what
>>>>>>> you’re trying to achieve and why, and to provide others a chance to spot
>>>>>>> potential flaws, alternatives and interactions with work you may not be
>>>>>>> aware of.
>>>>>>>
>>>>>>> It would be nice if there were an easy rubric for whether something
>>>>>>> needs feedback, but I don’t think there is. One person’s obvious
>>>>>>> change may be another’s obvious problem. So I think any decision that binds
>>>>>>> the project going forwards should have a lazy consensus DISCUSS thread at
>>>>>>> least.
>>>>>>>
>>>>>>> I don’t think it needs to be burdensome though - trivial API changes
>>>>>>> could begin while the DISCUSS thread is underway, expecting they usually
>>>>>>> won’t raise a murmur.
>>>>>>>
>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>
>>>>>>>
>>>>>>> Came up this morning / afternoon in dev slack:
>>>>>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>
>>>>>>> The gist of it: we're lacking clarity on whether the expectation on
>>>>>>> the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API
>>>>>>> modification or only on modifications where the author feels they are
>>>>>>> adjusting a paradigm / strategy for an API.
>>>>>>>
>>>>>>> The code style section on Public APIs is actually a little unclear:
>>>>>>> https://cassandra.apache.org/_/development/code_style.html
>>>>>>>
>>>>>>> Public APIs
>>>>>>>
>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>
>>>>>>>
>>>>>>> My .02:
>>>>>>> 1. We should rename that page to a "code contribution guide" as
>>>>>>> discussed on the slack thread
>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics,
>>>>>>> JMX, vtables, .java interfaces targeting user extension, etc) should hit
>>>>>>> the dev ML w/a [DISCUSS] thread.
>>>>>>>
>>>>>>> This takes the burden of trying to determine if a change is
>>>>>>> consistent w/existing strategy or not etc. off the author in isolation and
>>>>>>> allows devs to work concurrently on API changes w/out risk of someone else
>>>>>>> working on something that may inform their work or vice versa.
>>>>>>>
>>>>>>> We've learned that API's are *really really hard* to deprecate,
>>>>>>> disruptive to our users when we change or remove them, and can cause
>>>>>>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>>>>>>> discussions about JMX, etc. They're the definition of a "one-way-door"
>>>>>>> decision and represent a long-term maintenance burden commitment from the
>>>>>>> project.
>>>>>>>
>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>>>>>> quick consensus checks resolved via lazy consensus or after some slight
>>>>>>> discussion; ideally this wouldn't represent a huge burden of coordination
>>>>>>> on folks working on changes.
>>>>>>>
>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>
>>>>>>> ~Josh
>>>>>>>
>>>>>>>
>>>>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Ekaterina Dimitrova <e....@gmail.com>.
“ I do not personally think the project status thread is the right venue
for this, though a periodic dedicated “API Changes” thread might not be a
bad approach.”
Just to clarify, I do not suggest to use the status mail to respond with
concerns. But more like - having a link to the filter in the bi-weekly
report and then everyone can open it and check the list of tickets and
comment directly on the tickets or open a thread if they think the issue
deserves one.
Same as having link to the tickets that are blockers or tickets that need
reviewers. Whoever wants will have an easy way to get to those and take
whatever actions they want.
On Mon, 5 Dec 2022 at 10:07, Benedict <be...@apache.org> wrote:
> Perhaps you misunderstand my concern? I think these decisions need broader
> input, not just my input.
>
> Are you therefore asking why I do not monitor these topics and propose
> DISCUSS threads based on activities others are undertaking? This doesn’t
> seem like the right approach to me, but if we do not come to some policy
> approach here, I will try to schedule some time each quarter to scan for
> topics I think should have had a DISCUSS thread, and open them up for
> discussion.
>
> I do not personally think the project status thread is the right venue for
> this, though a periodic dedicated “API Changes” thread might not be a bad
> approach.
>
>
> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>
>
>
> Benedict, I am confused. If you are so much concerned about virtual tables
> or CQL why do you not track those components changes directly? People
> usually label them correctly I believe. Like that you would be able to
> provide feedback straight away rather than after the fact. It would be a
> win for everybody, no?
>
> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com>
> a écrit :
>
>> Quick idea - can we add a label in Jira API or something like that and
>> then Josh can filter those in the bi-weekly report? In the meantime if
>> there are big changes that people consider they need a DISCUSS thread for
>> they can always open one? I will be happy to help with the mentioned
>> filter/report.
>> Also +1 on having Contributing doc with broader discussion and directions
>> around API
>>
>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>
>>> I would be fine with a formal API change review period prior to release,
>>> but if we go that route people should expect to have to revisit work they
>>> completed a while back, and there should be no presumption that decisions
>>> taken without a DISCUSS thread should be preferred to alternative
>>> suggestions - and we should have a clear policy of reverting any work if it
>>> is not revisited based on the outcome of any discussion, since seeking
>>> broader input earlier was always an option. I expect this approach could
>>> lead to frustration, but it might actually be a better system than separate
>>> DISCUSS threads as the changes can be considered holistically.
>>>
>>> The idea that a DISCUSS thread for each change would be burdensome
>>> however is I think mistaken. Even if 70 were the true figure, it would have
>>> been around one per week, and they could easily have been batched. I’d also
>>> be fine with white listing some changes (eg JMX and warning messages) - but
>>> definitely not virtual tables or CQL. These APIs develop strong user
>>> dependencies, and are very hard to change.
>>>
>>> We should not restrict input on our main user experiences to the handful
>>> of people with time to closely monitor Jira, most of whom are not even
>>> users of Cassandra. We should be seeking the broadest visibility, including
>>> casual observers and non-contributors.
>>>
>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>
>>>
>>>
>>> It feels bit of overkill to me to require addition of any new virtual
>>> tables/JMX/configuration/knob to go through a discuss thread. If this would
>>> require 70 threads for the previous release I think this would easily
>>> become spammy and counter-productive.
>>>
>>> I think the burden should be on the maintainer to keep up with changes
>>> being added to the database and chime in any areas it feel responsible for,
>>> as it has been the case and has worked relatively well.
>>>
>>> I think it makes sense to look into improving visibility of API changes,
>>> so people can more easily review a summary of API changes versus reading
>>> through the whole changelog (perhaps we need a summarized API change log?).
>>>
>>> It would also help to have more explicit guidelines on what kinds of API
>>> changes are riskier and might require additional visibility via a DISCUSS
>>> thread.
>>>
>>> Also, would it make sense to introduce a new API review stage during
>>> release validation, and agree to revert/update any API changes that may be
>>> controversial that were not caught during normal review?
>>>
>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org>
>>> wrote:
>>>
>>>> Indeed that contribution policy should be clearer and not be on a page
>>>> titled code style, thanks for briging that up.
>>>>
>>>> If we consider all those things APIs, and additions are also considered
>>>> changes that require a DISCUSS thread, it turns out that almost any
>>>> not-bugfix ticket would require a mail list thread. In fact, if one goes
>>>> through CHANGES.txt it's easy to see that most entries would have required
>>>> a DISCUSS thread.
>>>>
>>>> I think that such a strict policy would only make us lose agility and
>>>> increase the burden of almost any contribution. After all, it's not that
>>>> changes without a DISCUSS thread happen in secret. Changes are publicly
>>>> visible on their tickets, those tickets are notified on Slack so anyone can
>>>> jump into the ticket discussions and set themselves as reviewers, and
>>>> reviewers can ask for DISCUSS threads whenever they think more opinions or
>>>> broader consensus are needed.
>>>>
>>>> Also, a previous DISCUSS thread is not going to impede that any changes
>>>> are going to be questioned later. We have seen changes that are proposed,
>>>> discussed and approved as CEPs, reviewed for weeks or months, and finally
>>>> committed, and still they are questioned shortly after that cycle, and
>>>> asked to be changed or discussed again. I don't think that an avalanche of
>>>> DISCUSS threads is going to improve that, since usually the problem is that
>>>> people don't have the time for deeply looking into the changes when they
>>>> are happening. I doubt that more notification channels are going to improve
>>>> that.
>>>>
>>>> Of course I'm not saying that there should never DISCUSS threads before
>>>> starting a change. Probably we can all agree that major changes and things
>>>> that break compatibility would need previous discussion.
>>>>
>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>>
>>>>> Thanks for opening this thread Josh,
>>>>>
>>>>> It seems perfectly normal to me that for important changes or
>>>>> questions we raise some discussion to the mailing list.
>>>>>
>>>>> My understanding of the current proposal implies that for the 4.1
>>>>> release we should have had to raise over 70 discussion threads.
>>>>> We have a minimum of 2 commiters required for every patch. Should we
>>>>> not trust them to update nodetool, the virtual tables or other things on
>>>>> their own?
>>>>>
>>>>> There is already multiple existing ways to track changes in specific
>>>>> code areas. I am personaly tracking the areas in which I am the most
>>>>> involved this way and I know that a lot of people do the same.
>>>>>
>>>>> To be transparent, It is not clear to me what the underlying issue is?
>>>>> Do we have some specific cases that illustrate the underlying problem?
>>>>> Thrift and JMX are from a different time in my opinion.
>>>>>
>>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com>
>>>>> a écrit :
>>>>>
>>>>>> +1 to moving that into it's own section outside the coding style page.
>>>>>>
>>>>>> Dinesh I also thought in terms of backward compatibility here. But
>>>>>> notice the discussion is about _any change_ to the API such as adding new
>>>>>> CQL functions. Would adding or changing an exception type or a user warning
>>>>>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>>>>>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>>
>>>>>> I wonder, you guys know the code better, if 'public APIs' could be
>>>>>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>>>>>> jenkins send an email when changes are detected on them. Overkill? bad
>>>>>> idea? :thinking:...
>>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>>
>>>>>> We should also very clearly list out what is considered a public API.
>>>>>> The current statement that we have is insufficient:
>>>>>>
>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system
>>>>>> properties, etc.
>>>>>>
>>>>>>
>>>>>> The guidance on treatment of public APIs should also move out of
>>>>>> "Code Style" page as it isn't strictly related to code style. Backward
>>>>>> compatibility of public APIs is a best practice & project policy.
>>>>>>
>>>>>>
>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>
>>>>>> I think some of that text also got garbled by mixing up how you
>>>>>> approach internal APIs and external APIs. We should probably clarify that
>>>>>> there are different burdens for each. Which is all my fault as the
>>>>>> formulator. I remember it being much clearer in my head.
>>>>>>
>>>>>> My view is the same as yours Josh. Evolving the database’s public
>>>>>> APIs is something that needs community consensus. The more visibility these
>>>>>> decisions get, the better the final outcome (usually). Even small API
>>>>>> changes need to be carefully considered to ensure the API evolves
>>>>>> coherently, and this is particularly true for something as complex and
>>>>>> central as CQL.
>>>>>>
>>>>>> A DISCUSS thread is a good forcing function to think about what
>>>>>> you’re trying to achieve and why, and to provide others a chance to spot
>>>>>> potential flaws, alternatives and interactions with work you may not be
>>>>>> aware of.
>>>>>>
>>>>>> It would be nice if there were an easy rubric for whether something
>>>>>> needs feedback, but I don’t think there is. One person’s obvious
>>>>>> change may be another’s obvious problem. So I think any decision that binds
>>>>>> the project going forwards should have a lazy consensus DISCUSS thread at
>>>>>> least.
>>>>>>
>>>>>> I don’t think it needs to be burdensome though - trivial API changes
>>>>>> could begin while the DISCUSS thread is underway, expecting they usually
>>>>>> won’t raise a murmur.
>>>>>>
>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>
>>>>>>
>>>>>> Came up this morning / afternoon in dev slack:
>>>>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>
>>>>>> The gist of it: we're lacking clarity on whether the expectation on
>>>>>> the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API
>>>>>> modification or only on modifications where the author feels they are
>>>>>> adjusting a paradigm / strategy for an API.
>>>>>>
>>>>>> The code style section on Public APIs is actually a little unclear:
>>>>>> https://cassandra.apache.org/_/development/code_style.html
>>>>>>
>>>>>> Public APIs
>>>>>>
>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>
>>>>>>
>>>>>> My .02:
>>>>>> 1. We should rename that page to a "code contribution guide" as
>>>>>> discussed on the slack thread
>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics,
>>>>>> JMX, vtables, .java interfaces targeting user extension, etc) should hit
>>>>>> the dev ML w/a [DISCUSS] thread.
>>>>>>
>>>>>> This takes the burden of trying to determine if a change is
>>>>>> consistent w/existing strategy or not etc. off the author in isolation and
>>>>>> allows devs to work concurrently on API changes w/out risk of someone else
>>>>>> working on something that may inform their work or vice versa.
>>>>>>
>>>>>> We've learned that API's are *really really hard* to deprecate,
>>>>>> disruptive to our users when we change or remove them, and can cause
>>>>>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>>>>>> discussions about JMX, etc. They're the definition of a "one-way-door"
>>>>>> decision and represent a long-term maintenance burden commitment from the
>>>>>> project.
>>>>>>
>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>>>>> quick consensus checks resolved via lazy consensus or after some slight
>>>>>> discussion; ideally this wouldn't represent a huge burden of coordination
>>>>>> on folks working on changes.
>>>>>>
>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>
>>>>>> ~Josh
>>>>>>
>>>>>>
>>>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benedict <be...@apache.org>.
Perhaps you misunderstand my concern? I think these decisions need broader input, not just my input.
Are you therefore asking why I do not monitor these topics and propose DISCUSS threads based on activities others are undertaking? This doesn’t seem like the right approach to me, but if we do not come to some policy approach here, I will try to schedule some time each quarter to scan for topics I think should have had a DISCUSS thread, and open them up for discussion.
I do not personally think the project status thread is the right venue for this, though a periodic dedicated “API Changes” thread might not be a bad approach.
> On 5 Dec 2022, at 14:16, Benjamin Lerer <b....@gmail.com> wrote:
>
>
> Benedict, I am confused. If you are so much concerned about virtual tables or CQL why do you not track those components changes directly? People usually label them correctly I believe. Like that you would be able to provide feedback straight away rather than after the fact. It would be a win for everybody, no?
>
>> Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com> a écrit :
>> Quick idea - can we add a label in Jira API or something like that and then Josh can filter those in the bi-weekly report? In the meantime if there are big changes that people consider they need a DISCUSS thread for they can always open one? I will be happy to help with the mentioned filter/report.
>> Also +1 on having Contributing doc with broader discussion and directions around API
>>
>>> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>>> I would be fine with a formal API change review period prior to release, but if we go that route people should expect to have to revisit work they completed a while back, and there should be no presumption that decisions taken without a DISCUSS thread should be preferred to alternative suggestions - and we should have a clear policy of reverting any work if it is not revisited based on the outcome of any discussion, since seeking broader input earlier was always an option. I expect this approach could lead to frustration, but it might actually be a better system than separate DISCUSS threads as the changes can be considered holistically.
>>>
>>> The idea that a DISCUSS thread for each change would be burdensome however is I think mistaken. Even if 70 were the true figure, it would have been around one per week, and they could easily have been batched. I’d also be fine with white listing some changes (eg JMX and warning messages) - but definitely not virtual tables or CQL. These APIs develop strong user dependencies, and are very hard to change.
>>>
>>> We should not restrict input on our main user experiences to the handful of people with time to closely monitor Jira, most of whom are not even users of Cassandra. We should be seeking the broadest visibility, including casual observers and non-contributors.
>>>
>>>>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>>>>
>>>>
>>>
>>>> It feels bit of overkill to me to require addition of any new virtual tables/JMX/configuration/knob to go through a discuss thread. If this would require 70 threads for the previous release I think this would easily become spammy and counter-productive.
>>>>
>>>> I think the burden should be on the maintainer to keep up with changes being added to the database and chime in any areas it feel responsible for, as it has been the case and has worked relatively well.
>>>>
>>>> I think it makes sense to look into improving visibility of API changes, so people can more easily review a summary of API changes versus reading through the whole changelog (perhaps we need a summarized API change log?).
>>>>
>>>> It would also help to have more explicit guidelines on what kinds of API changes are riskier and might require additional visibility via a DISCUSS thread.
>>>>
>>>> Also, would it make sense to introduce a new API review stage during release validation, and agree to revert/update any API changes that may be controversial that were not caught during normal review?
>>>>
>>>>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
>>>>
>>>>> Indeed that contribution policy should be clearer and not be on a page titled code style, thanks for briging that up.
>>>>>
>>>>> If we consider all those things APIs, and additions are also considered changes that require a DISCUSS thread, it turns out that almost any not-bugfix ticket would require a mail list thread. In fact, if one goes through CHANGES.txt it's easy to see that most entries would have required a DISCUSS thread.
>>>>>
>>>>> I think that such a strict policy would only make us lose agility and increase the burden of almost any contribution. After all, it's not that changes without a DISCUSS thread happen in secret. Changes are publicly visible on their tickets, those tickets are notified on Slack so anyone can jump into the ticket discussions and set themselves as reviewers, and reviewers can ask for DISCUSS threads whenever they think more opinions or broader consensus are needed.
>>>>>
>>>>> Also, a previous DISCUSS thread is not going to impede that any changes are going to be questioned later. We have seen changes that are proposed, discussed and approved as CEPs, reviewed for weeks or months, and finally committed, and still they are questioned shortly after that cycle, and asked to be changed or discussed again. I don't think that an avalanche of DISCUSS threads is going to improve that, since usually the problem is that people don't have the time for deeply looking into the changes when they are happening. I doubt that more notification channels are going to improve that.
>>>>>
>>>>> Of course I'm not saying that there should never DISCUSS threads before starting a change. Probably we can all agree that major changes and things that break compatibility would need previous discussion.
>>>>>
>>>>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>>>> Thanks for opening this thread Josh,
>>>>>>
>>>>>> It seems perfectly normal to me that for important changes or questions we raise some discussion to the mailing list.
>>>>>>
>>>>>> My understanding of the current proposal implies that for the 4.1 release we should have had to raise over 70 discussion threads.
>>>>>> We have a minimum of 2 commiters required for every patch. Should we not trust them to update nodetool, the virtual tables or other things on their own?
>>>>>>
>>>>>> There is already multiple existing ways to track changes in specific code areas. I am personaly tracking the areas in which I am the most involved this way and I know that a lot of people do the same.
>>>>>>
>>>>>> To be transparent, It is not clear to me what the underlying issue is? Do we have some specific cases that illustrate the underlying problem? Thrift and JMX are from a different time in my opinion.
>>>>>>
>>>>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a écrit :
>>>>>>> +1 to moving that into it's own section outside the coding style page.
>>>>>>>
>>>>>>> Dinesh I also thought in terms of backward compatibility here. But notice the discussion is about _any change_ to the API such as adding new CQL functions. Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also? I wonder if we're talking ourselves into opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>>>
>>>>>>> I wonder, you guys know the code better, if 'public APIs' could be matched to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send an email when changes are detected on them. Overkill? bad idea? :thinking:...
>>>>>>>
>>>>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>>>> We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
>>>>>>>>
>>>>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
>>>>>>>>
>>>>>>>> The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
>>>>>>>>
>>>>>>>>
>>>>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>>>>
>>>>>>>>> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>>>>>>>>>
>>>>>>>>> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>>>>>>>>>
>>>>>>>>> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>>>>>>>>>
>>>>>>>>> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>>>>>>>>>
>>>>>>>>> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>>>>>>>>>
>>>>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>>>>
>>>>>>>>>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>>>>>>>>>
>>>>>>>>>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>>>>>>>>>>
>>>>>>>>>>> Public APIs
>>>>>>>>>>>
>>>>>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>>>>
>>>>>>>>>> My .02:
>>>>>>>>>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>>>>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>>>>>>>>>
>>>>>>>>>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>>>>>>>>>
>>>>>>>>>> We've learned that API's are really really hard to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>>>>>>>>>
>>>>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>>>>>>>>>
>>>>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>>>>
>>>>>>>>>> ~Josh
>>>>>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benjamin Lerer <b....@gmail.com>.
Benedict, I am confused. If you are so much concerned about virtual tables
or CQL why do you not track those components changes directly? People
usually label them correctly I believe. Like that you would be able to
provide feedback straight away rather than after the fact. It would be a
win for everybody, no?
Le lun. 5 déc. 2022 à 15:10, Ekaterina Dimitrova <e....@gmail.com> a
écrit :
> Quick idea - can we add a label in Jira API or something like that and
> then Josh can filter those in the bi-weekly report? In the meantime if
> there are big changes that people consider they need a DISCUSS thread for
> they can always open one? I will be happy to help with the mentioned
> filter/report.
> Also +1 on having Contributing doc with broader discussion and directions
> around API
>
> On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
>
>> I would be fine with a formal API change review period prior to release,
>> but if we go that route people should expect to have to revisit work they
>> completed a while back, and there should be no presumption that decisions
>> taken without a DISCUSS thread should be preferred to alternative
>> suggestions - and we should have a clear policy of reverting any work if it
>> is not revisited based on the outcome of any discussion, since seeking
>> broader input earlier was always an option. I expect this approach could
>> lead to frustration, but it might actually be a better system than separate
>> DISCUSS threads as the changes can be considered holistically.
>>
>> The idea that a DISCUSS thread for each change would be burdensome
>> however is I think mistaken. Even if 70 were the true figure, it would have
>> been around one per week, and they could easily have been batched. I’d also
>> be fine with white listing some changes (eg JMX and warning messages) - but
>> definitely not virtual tables or CQL. These APIs develop strong user
>> dependencies, and are very hard to change.
>>
>> We should not restrict input on our main user experiences to the handful
>> of people with time to closely monitor Jira, most of whom are not even
>> users of Cassandra. We should be seeking the broadest visibility, including
>> casual observers and non-contributors.
>>
>> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>>
>>
>>
>> It feels bit of overkill to me to require addition of any new virtual
>> tables/JMX/configuration/knob to go through a discuss thread. If this would
>> require 70 threads for the previous release I think this would easily
>> become spammy and counter-productive.
>>
>> I think the burden should be on the maintainer to keep up with changes
>> being added to the database and chime in any areas it feel responsible for,
>> as it has been the case and has worked relatively well.
>>
>> I think it makes sense to look into improving visibility of API changes,
>> so people can more easily review a summary of API changes versus reading
>> through the whole changelog (perhaps we need a summarized API change log?).
>>
>> It would also help to have more explicit guidelines on what kinds of API
>> changes are riskier and might require additional visibility via a DISCUSS
>> thread.
>>
>> Also, would it make sense to introduce a new API review stage during
>> release validation, and agree to revert/update any API changes that may be
>> controversial that were not caught during normal review?
>>
>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org>
>> wrote:
>>
>>> Indeed that contribution policy should be clearer and not be on a page
>>> titled code style, thanks for briging that up.
>>>
>>> If we consider all those things APIs, and additions are also considered
>>> changes that require a DISCUSS thread, it turns out that almost any
>>> not-bugfix ticket would require a mail list thread. In fact, if one goes
>>> through CHANGES.txt it's easy to see that most entries would have required
>>> a DISCUSS thread.
>>>
>>> I think that such a strict policy would only make us lose agility and
>>> increase the burden of almost any contribution. After all, it's not that
>>> changes without a DISCUSS thread happen in secret. Changes are publicly
>>> visible on their tickets, those tickets are notified on Slack so anyone can
>>> jump into the ticket discussions and set themselves as reviewers, and
>>> reviewers can ask for DISCUSS threads whenever they think more opinions or
>>> broader consensus are needed.
>>>
>>> Also, a previous DISCUSS thread is not going to impede that any changes
>>> are going to be questioned later. We have seen changes that are proposed,
>>> discussed and approved as CEPs, reviewed for weeks or months, and finally
>>> committed, and still they are questioned shortly after that cycle, and
>>> asked to be changed or discussed again. I don't think that an avalanche of
>>> DISCUSS threads is going to improve that, since usually the problem is that
>>> people don't have the time for deeply looking into the changes when they
>>> are happening. I doubt that more notification channels are going to improve
>>> that.
>>>
>>> Of course I'm not saying that there should never DISCUSS threads before
>>> starting a change. Probably we can all agree that major changes and things
>>> that break compatibility would need previous discussion.
>>>
>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>>
>>>> Thanks for opening this thread Josh,
>>>>
>>>> It seems perfectly normal to me that for important changes or questions
>>>> we raise some discussion to the mailing list.
>>>>
>>>> My understanding of the current proposal implies that for the 4.1
>>>> release we should have had to raise over 70 discussion threads.
>>>> We have a minimum of 2 commiters required for every patch. Should we
>>>> not trust them to update nodetool, the virtual tables or other things on
>>>> their own?
>>>>
>>>> There is already multiple existing ways to track changes in specific
>>>> code areas. I am personaly tracking the areas in which I am the most
>>>> involved this way and I know that a lot of people do the same.
>>>>
>>>> To be transparent, It is not clear to me what the underlying issue is?
>>>> Do we have some specific cases that illustrate the underlying problem?
>>>> Thrift and JMX are from a different time in my opinion.
>>>>
>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com>
>>>> a écrit :
>>>>
>>>>> +1 to moving that into it's own section outside the coding style page.
>>>>>
>>>>> Dinesh I also thought in terms of backward compatibility here. But
>>>>> notice the discussion is about _any change_ to the API such as adding new
>>>>> CQL functions. Would adding or changing an exception type or a user warning
>>>>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>>>>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>>
>>>>> I wonder, you guys know the code better, if 'public APIs' could be
>>>>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>>>>> jenkins send an email when changes are detected on them. Overkill? bad
>>>>> idea? :thinking:...
>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>>
>>>>> We should also very clearly list out what is considered a public API.
>>>>> The current statement that we have is insufficient:
>>>>>
>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system
>>>>> properties, etc.
>>>>>
>>>>>
>>>>> The guidance on treatment of public APIs should also move out of "Code
>>>>> Style" page as it isn't strictly related to code style. Backward
>>>>> compatibility of public APIs is a best practice & project policy.
>>>>>
>>>>>
>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>
>>>>> I think some of that text also got garbled by mixing up how you
>>>>> approach internal APIs and external APIs. We should probably clarify that
>>>>> there are different burdens for each. Which is all my fault as the
>>>>> formulator. I remember it being much clearer in my head.
>>>>>
>>>>> My view is the same as yours Josh. Evolving the database’s public APIs
>>>>> is something that needs community consensus. The more visibility these
>>>>> decisions get, the better the final outcome (usually). Even small API
>>>>> changes need to be carefully considered to ensure the API evolves
>>>>> coherently, and this is particularly true for something as complex and
>>>>> central as CQL.
>>>>>
>>>>> A DISCUSS thread is a good forcing function to think about what you’re
>>>>> trying to achieve and why, and to provide others a chance to spot potential
>>>>> flaws, alternatives and interactions with work you may not be aware of.
>>>>>
>>>>> It would be nice if there were an easy rubric for whether something
>>>>> needs feedback, but I don’t think there is. One person’s obvious
>>>>> change may be another’s obvious problem. So I think any decision that binds
>>>>> the project going forwards should have a lazy consensus DISCUSS thread at
>>>>> least.
>>>>>
>>>>> I don’t think it needs to be burdensome though - trivial API changes
>>>>> could begin while the DISCUSS thread is underway, expecting they usually
>>>>> won’t raise a murmur.
>>>>>
>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>
>>>>>
>>>>> Came up this morning / afternoon in dev slack:
>>>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>
>>>>> The gist of it: we're lacking clarity on whether the expectation on
>>>>> the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API
>>>>> modification or only on modifications where the author feels they are
>>>>> adjusting a paradigm / strategy for an API.
>>>>>
>>>>> The code style section on Public APIs is actually a little unclear:
>>>>> https://cassandra.apache.org/_/development/code_style.html
>>>>>
>>>>> Public APIs
>>>>>
>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>
>>>>>
>>>>> My .02:
>>>>> 1. We should rename that page to a "code contribution guide" as
>>>>> discussed on the slack thread
>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
>>>>> vtables, .java interfaces targeting user extension, etc) should hit the dev
>>>>> ML w/a [DISCUSS] thread.
>>>>>
>>>>> This takes the burden of trying to determine if a change is consistent
>>>>> w/existing strategy or not etc. off the author in isolation and allows devs
>>>>> to work concurrently on API changes w/out risk of someone else working on
>>>>> something that may inform their work or vice versa.
>>>>>
>>>>> We've learned that API's are *really really hard* to deprecate,
>>>>> disruptive to our users when we change or remove them, and can cause
>>>>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>>>>> discussions about JMX, etc. They're the definition of a "one-way-door"
>>>>> decision and represent a long-term maintenance burden commitment from the
>>>>> project.
>>>>>
>>>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>>>> quick consensus checks resolved via lazy consensus or after some slight
>>>>> discussion; ideally this wouldn't represent a huge burden of coordination
>>>>> on folks working on changes.
>>>>>
>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>
>>>>> ~Josh
>>>>>
>>>>>
>>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Ekaterina Dimitrova <e....@gmail.com>.
Quick idea - can we add a label in Jira API or something like that and then
Josh can filter those in the bi-weekly report? In the meantime if there are
big changes that people consider they need a DISCUSS thread for they can
always open one? I will be happy to help with the mentioned filter/report.
Also +1 on having Contributing doc with broader discussion and directions
around API
On Mon, 5 Dec 2022 at 8:32, Benedict <be...@apache.org> wrote:
> I would be fine with a formal API change review period prior to release,
> but if we go that route people should expect to have to revisit work they
> completed a while back, and there should be no presumption that decisions
> taken without a DISCUSS thread should be preferred to alternative
> suggestions - and we should have a clear policy of reverting any work if it
> is not revisited based on the outcome of any discussion, since seeking
> broader input earlier was always an option. I expect this approach could
> lead to frustration, but it might actually be a better system than separate
> DISCUSS threads as the changes can be considered holistically.
>
> The idea that a DISCUSS thread for each change would be burdensome however
> is I think mistaken. Even if 70 were the true figure, it would have been
> around one per week, and they could easily have been batched. I’d also be
> fine with white listing some changes (eg JMX and warning messages) - but
> definitely not virtual tables or CQL. These APIs develop strong user
> dependencies, and are very hard to change.
>
> We should not restrict input on our main user experiences to the handful
> of people with time to closely monitor Jira, most of whom are not even
> users of Cassandra. We should be seeking the broadest visibility, including
> casual observers and non-contributors.
>
> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>
>
>
> It feels bit of overkill to me to require addition of any new virtual
> tables/JMX/configuration/knob to go through a discuss thread. If this would
> require 70 threads for the previous release I think this would easily
> become spammy and counter-productive.
>
> I think the burden should be on the maintainer to keep up with changes
> being added to the database and chime in any areas it feel responsible for,
> as it has been the case and has worked relatively well.
>
> I think it makes sense to look into improving visibility of API changes,
> so people can more easily review a summary of API changes versus reading
> through the whole changelog (perhaps we need a summarized API change log?).
>
> It would also help to have more explicit guidelines on what kinds of API
> changes are riskier and might require additional visibility via a DISCUSS
> thread.
>
> Also, would it make sense to introduce a new API review stage during
> release validation, and agree to revert/update any API changes that may be
> controversial that were not caught during normal review?
>
> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org>
> wrote:
>
>> Indeed that contribution policy should be clearer and not be on a page
>> titled code style, thanks for briging that up.
>>
>> If we consider all those things APIs, and additions are also considered
>> changes that require a DISCUSS thread, it turns out that almost any
>> not-bugfix ticket would require a mail list thread. In fact, if one goes
>> through CHANGES.txt it's easy to see that most entries would have required
>> a DISCUSS thread.
>>
>> I think that such a strict policy would only make us lose agility and
>> increase the burden of almost any contribution. After all, it's not that
>> changes without a DISCUSS thread happen in secret. Changes are publicly
>> visible on their tickets, those tickets are notified on Slack so anyone can
>> jump into the ticket discussions and set themselves as reviewers, and
>> reviewers can ask for DISCUSS threads whenever they think more opinions or
>> broader consensus are needed.
>>
>> Also, a previous DISCUSS thread is not going to impede that any changes
>> are going to be questioned later. We have seen changes that are proposed,
>> discussed and approved as CEPs, reviewed for weeks or months, and finally
>> committed, and still they are questioned shortly after that cycle, and
>> asked to be changed or discussed again. I don't think that an avalanche of
>> DISCUSS threads is going to improve that, since usually the problem is that
>> people don't have the time for deeply looking into the changes when they
>> are happening. I doubt that more notification channels are going to improve
>> that.
>>
>> Of course I'm not saying that there should never DISCUSS threads before
>> starting a change. Probably we can all agree that major changes and things
>> that break compatibility would need previous discussion.
>>
>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>
>>> Thanks for opening this thread Josh,
>>>
>>> It seems perfectly normal to me that for important changes or questions
>>> we raise some discussion to the mailing list.
>>>
>>> My understanding of the current proposal implies that for the 4.1
>>> release we should have had to raise over 70 discussion threads.
>>> We have a minimum of 2 commiters required for every patch. Should we not
>>> trust them to update nodetool, the virtual tables or other things on their
>>> own?
>>>
>>> There is already multiple existing ways to track changes in specific
>>> code areas. I am personaly tracking the areas in which I am the most
>>> involved this way and I know that a lot of people do the same.
>>>
>>> To be transparent, It is not clear to me what the underlying issue is?
>>> Do we have some specific cases that illustrate the underlying problem?
>>> Thrift and JMX are from a different time in my opinion.
>>>
>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com>
>>> a écrit :
>>>
>>>> +1 to moving that into it's own section outside the coding style page.
>>>>
>>>> Dinesh I also thought in terms of backward compatibility here. But
>>>> notice the discussion is about _any change_ to the API such as adding new
>>>> CQL functions. Would adding or changing an exception type or a user warning
>>>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>>>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>
>>>> I wonder, you guys know the code better, if 'public APIs' could be
>>>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>>>> jenkins send an email when changes are detected on them. Overkill? bad
>>>> idea? :thinking:...
>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>
>>>> We should also very clearly list out what is considered a public API.
>>>> The current statement that we have is insufficient:
>>>>
>>>> public APIs, including CQL, virtual tables, JMX, yaml, system
>>>> properties, etc.
>>>>
>>>>
>>>> The guidance on treatment of public APIs should also move out of "Code
>>>> Style" page as it isn't strictly related to code style. Backward
>>>> compatibility of public APIs is a best practice & project policy.
>>>>
>>>>
>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>
>>>> I think some of that text also got garbled by mixing up how you
>>>> approach internal APIs and external APIs. We should probably clarify that
>>>> there are different burdens for each. Which is all my fault as the
>>>> formulator. I remember it being much clearer in my head.
>>>>
>>>> My view is the same as yours Josh. Evolving the database’s public APIs
>>>> is something that needs community consensus. The more visibility these
>>>> decisions get, the better the final outcome (usually). Even small API
>>>> changes need to be carefully considered to ensure the API evolves
>>>> coherently, and this is particularly true for something as complex and
>>>> central as CQL.
>>>>
>>>> A DISCUSS thread is a good forcing function to think about what you’re
>>>> trying to achieve and why, and to provide others a chance to spot potential
>>>> flaws, alternatives and interactions with work you may not be aware of.
>>>>
>>>> It would be nice if there were an easy rubric for whether something
>>>> needs feedback, but I don’t think there is. One person’s obvious
>>>> change may be another’s obvious problem. So I think any decision that binds
>>>> the project going forwards should have a lazy consensus DISCUSS thread at
>>>> least.
>>>>
>>>> I don’t think it needs to be burdensome though - trivial API changes
>>>> could begin while the DISCUSS thread is underway, expecting they usually
>>>> won’t raise a murmur.
>>>>
>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>
>>>>
>>>> Came up this morning / afternoon in dev slack:
>>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>
>>>> The gist of it: we're lacking clarity on whether the expectation on the
>>>> project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification
>>>> or only on modifications where the author feels they are adjusting a
>>>> paradigm / strategy for an API.
>>>>
>>>> The code style section on Public APIs is actually a little unclear:
>>>> https://cassandra.apache.org/_/development/code_style.html
>>>>
>>>> Public APIs
>>>>
>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>
>>>>
>>>> My .02:
>>>> 1. We should rename that page to a "code contribution guide" as
>>>> discussed on the slack thread
>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
>>>> vtables, .java interfaces targeting user extension, etc) should hit the dev
>>>> ML w/a [DISCUSS] thread.
>>>>
>>>> This takes the burden of trying to determine if a change is consistent
>>>> w/existing strategy or not etc. off the author in isolation and allows devs
>>>> to work concurrently on API changes w/out risk of someone else working on
>>>> something that may inform their work or vice versa.
>>>>
>>>> We've learned that API's are *really really hard* to deprecate,
>>>> disruptive to our users when we change or remove them, and can cause
>>>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>>>> discussions about JMX, etc. They're the definition of a "one-way-door"
>>>> decision and represent a long-term maintenance burden commitment from the
>>>> project.
>>>>
>>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>>> quick consensus checks resolved via lazy consensus or after some slight
>>>> discussion; ideally this wouldn't represent a huge burden of coordination
>>>> on folks working on changes.
>>>>
>>>> So that's 1 opinion. What other opinions are out there?
>>>>
>>>> ~Josh
>>>>
>>>>
>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benedict <be...@apache.org>.
I would be fine with a formal API change review period prior to release, but if we go that route people should expect to have to revisit work they completed a while back, and there should be no presumption that decisions taken without a DISCUSS thread should be preferred to alternative suggestions - and we should have a clear policy of reverting any work if it is not revisited based on the outcome of any discussion, since seeking broader input earlier was always an option. I expect this approach could lead to frustration, but it might actually be a better system than separate DISCUSS threads as the changes can be considered holistically.
The idea that a DISCUSS thread for each change would be burdensome however is I think mistaken. Even if 70 were the true figure, it would have been around one per week, and they could easily have been batched. I’d also be fine with white listing some changes (eg JMX and warning messages) - but definitely not virtual tables or CQL. These APIs develop strong user dependencies, and are very hard to change.
We should not restrict input on our main user experiences to the handful of people with time to closely monitor Jira, most of whom are not even users of Cassandra. We should be seeking the broadest visibility, including casual observers and non-contributors.
> On 5 Dec 2022, at 13:05, Paulo Motta <pa...@gmail.com> wrote:
>
>
> It feels bit of overkill to me to require addition of any new virtual tables/JMX/configuration/knob to go through a discuss thread. If this would require 70 threads for the previous release I think this would easily become spammy and counter-productive.
>
> I think the burden should be on the maintainer to keep up with changes being added to the database and chime in any areas it feel responsible for, as it has been the case and has worked relatively well.
>
> I think it makes sense to look into improving visibility of API changes, so people can more easily review a summary of API changes versus reading through the whole changelog (perhaps we need a summarized API change log?).
>
> It would also help to have more explicit guidelines on what kinds of API changes are riskier and might require additional visibility via a DISCUSS thread.
>
> Also, would it make sense to introduce a new API review stage during release validation, and agree to revert/update any API changes that may be controversial that were not caught during normal review?
>
>> On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
>
>> Indeed that contribution policy should be clearer and not be on a page titled code style, thanks for briging that up.
>>
>> If we consider all those things APIs, and additions are also considered changes that require a DISCUSS thread, it turns out that almost any not-bugfix ticket would require a mail list thread. In fact, if one goes through CHANGES.txt it's easy to see that most entries would have required a DISCUSS thread.
>>
>> I think that such a strict policy would only make us lose agility and increase the burden of almost any contribution. After all, it's not that changes without a DISCUSS thread happen in secret. Changes are publicly visible on their tickets, those tickets are notified on Slack so anyone can jump into the ticket discussions and set themselves as reviewers, and reviewers can ask for DISCUSS threads whenever they think more opinions or broader consensus are needed.
>>
>> Also, a previous DISCUSS thread is not going to impede that any changes are going to be questioned later. We have seen changes that are proposed, discussed and approved as CEPs, reviewed for weeks or months, and finally committed, and still they are questioned shortly after that cycle, and asked to be changed or discussed again. I don't think that an avalanche of DISCUSS threads is going to improve that, since usually the problem is that people don't have the time for deeply looking into the changes when they are happening. I doubt that more notification channels are going to improve that.
>>
>> Of course I'm not saying that there should never DISCUSS threads before starting a change. Probably we can all agree that major changes and things that break compatibility would need previous discussion.
>>
>>> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>>> Thanks for opening this thread Josh,
>>>
>>> It seems perfectly normal to me that for important changes or questions we raise some discussion to the mailing list.
>>>
>>> My understanding of the current proposal implies that for the 4.1 release we should have had to raise over 70 discussion threads.
>>> We have a minimum of 2 commiters required for every patch. Should we not trust them to update nodetool, the virtual tables or other things on their own?
>>>
>>> There is already multiple existing ways to track changes in specific code areas. I am personaly tracking the areas in which I am the most involved this way and I know that a lot of people do the same.
>>>
>>> To be transparent, It is not clear to me what the underlying issue is? Do we have some specific cases that illustrate the underlying problem? Thrift and JMX are from a different time in my opinion.
>>>
>>>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a écrit :
>>>> +1 to moving that into it's own section outside the coding style page.
>>>>
>>>> Dinesh I also thought in terms of backward compatibility here. But notice the discussion is about _any change_ to the API such as adding new CQL functions. Would adding or changing an exception type or a user warning qualify for a DISCUSS thread also? I wonder if we're talking ourselves into opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>>
>>>> I wonder, you guys know the code better, if 'public APIs' could be matched to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send an email when changes are detected on them. Overkill? bad idea? :thinking:...
>>>>
>>>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>>> We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
>>>>>
>>>>>> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
>>>>>
>>>>> The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
>>>>>
>>>>>
>>>>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>>>>
>>>>>> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>>>>>>
>>>>>> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>>>>>>
>>>>>> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>>>>>>
>>>>>> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>>>>>>
>>>>>> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>>>>>>
>>>>>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>>>>>
>>>>>>>
>>>>>>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>>>>>
>>>>>>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>>>>>>
>>>>>>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>>>>>>>
>>>>>>>> Public APIs
>>>>>>>>
>>>>>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>>>>>
>>>>>>> My .02:
>>>>>>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>>>>>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>>>>>>
>>>>>>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>>>>>>
>>>>>>> We've learned that API's are really really hard to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>>>>>>
>>>>>>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>>>>>>
>>>>>>> So that's 1 opinion. What other opinions are out there?
>>>>>>>
>>>>>>> ~Josh
>>>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Mick Semb Wever <mc...@apache.org>.
>
> I think it makes sense to look into improving visibility of API changes,
> so people can more easily review a summary of API changes versus reading
> through the whole changelog (perhaps we need a summarized API change log?).
>
Agree Paulo.
Observers should be able to see all API changes early. We can do better
than telling downstream users/devs "you have to listen to all jira tickets"
or "you have to watch the code and pick up changes". Watching CHANGES.txt
or NEWS.txt or CEPs doesn't solve the need either.
Observing such changes as early as possible can save a significant amount
of effort and headache later on, and should be encouraged. If done
correctly I can imagine it will help welcome more contributors.
I can also see that we can improve at, and have a better shared
understanding of, categorising the types of API changes:
addition/change/deprecation/removal, signature/output/behavioural, API/SPI.
So I can see value here for both observers and for ourselves.
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Paulo Motta <pa...@gmail.com>.
It feels bit of overkill to me to require addition of any new virtual
tables/JMX/configuration/knob to go through a discuss thread. If this would
require 70 threads for the previous release I think this would easily
become spammy and counter-productive.
I think the burden should be on the maintainer to keep up with changes
being added to the database and chime in any areas it feel responsible for,
as it has been the case and has worked relatively well.
I think it makes sense to look into improving visibility of API changes, so
people can more easily review a summary of API changes versus reading
through the whole changelog (perhaps we need a summarized API change log?).
It would also help to have more explicit guidelines on what kinds of API
changes are riskier and might require additional visibility via a DISCUSS
thread.
Also, would it make sense to introduce a new API review stage during
release validation, and agree to revert/update any API changes that may be
controversial that were not caught during normal review?
On Mon, 5 Dec 2022 at 06:49 Andrés de la Peña <ad...@apache.org> wrote:
> Indeed that contribution policy should be clearer and not be on a page
> titled code style, thanks for briging that up.
>
> If we consider all those things APIs, and additions are also considered
> changes that require a DISCUSS thread, it turns out that almost any
> not-bugfix ticket would require a mail list thread. In fact, if one goes
> through CHANGES.txt it's easy to see that most entries would have required
> a DISCUSS thread.
>
> I think that such a strict policy would only make us lose agility and
> increase the burden of almost any contribution. After all, it's not that
> changes without a DISCUSS thread happen in secret. Changes are publicly
> visible on their tickets, those tickets are notified on Slack so anyone can
> jump into the ticket discussions and set themselves as reviewers, and
> reviewers can ask for DISCUSS threads whenever they think more opinions or
> broader consensus are needed.
>
> Also, a previous DISCUSS thread is not going to impede that any changes
> are going to be questioned later. We have seen changes that are proposed,
> discussed and approved as CEPs, reviewed for weeks or months, and finally
> committed, and still they are questioned shortly after that cycle, and
> asked to be changed or discussed again. I don't think that an avalanche of
> DISCUSS threads is going to improve that, since usually the problem is that
> people don't have the time for deeply looking into the changes when they
> are happening. I doubt that more notification channels are going to improve
> that.
>
> Of course I'm not saying that there should never DISCUSS threads before
> starting a change. Probably we can all agree that major changes and things
> that break compatibility would need previous discussion.
>
> On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
>
>> Thanks for opening this thread Josh,
>>
>> It seems perfectly normal to me that for important changes or questions
>> we raise some discussion to the mailing list.
>>
>> My understanding of the current proposal implies that for the 4.1
>> release we should have had to raise over 70 discussion threads.
>> We have a minimum of 2 commiters required for every patch. Should we not
>> trust them to update nodetool, the virtual tables or other things on their
>> own?
>>
>> There is already multiple existing ways to track changes in specific code
>> areas. I am personaly tracking the areas in which I am the most involved
>> this way and I know that a lot of people do the same.
>>
>> To be transparent, It is not clear to me what the underlying issue is? Do
>> we have some specific cases that illustrate the underlying problem? Thrift
>> and JMX are from a different time in my opinion.
>>
>> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com>
>> a écrit :
>>
>>> +1 to moving that into it's own section outside the coding style page.
>>>
>>> Dinesh I also thought in terms of backward compatibility here. But
>>> notice the discussion is about _any change_ to the API such as adding new
>>> CQL functions. Would adding or changing an exception type or a user warning
>>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>>
>>> I wonder, you guys know the code better, if 'public APIs' could be
>>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>>> jenkins send an email when changes are detected on them. Overkill? bad
>>> idea? :thinking:...
>>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>>
>>> We should also very clearly list out what is considered a public API.
>>> The current statement that we have is insufficient:
>>>
>>> public APIs, including CQL, virtual tables, JMX, yaml, system
>>> properties, etc.
>>>
>>>
>>> The guidance on treatment of public APIs should also move out of "Code
>>> Style" page as it isn't strictly related to code style. Backward
>>> compatibility of public APIs is a best practice & project policy.
>>>
>>>
>>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>>
>>> I think some of that text also got garbled by mixing up how you approach
>>> internal APIs and external APIs. We should probably clarify that there are
>>> different burdens for each. Which is all my fault as the formulator. I
>>> remember it being much clearer in my head.
>>>
>>> My view is the same as yours Josh. Evolving the database’s public APIs
>>> is something that needs community consensus. The more visibility these
>>> decisions get, the better the final outcome (usually). Even small API
>>> changes need to be carefully considered to ensure the API evolves
>>> coherently, and this is particularly true for something as complex and
>>> central as CQL.
>>>
>>> A DISCUSS thread is a good forcing function to think about what you’re
>>> trying to achieve and why, and to provide others a chance to spot potential
>>> flaws, alternatives and interactions with work you may not be aware of.
>>>
>>> It would be nice if there were an easy rubric for whether something
>>> needs feedback, but I don’t think there is. One person’s obvious change
>>> may be another’s obvious problem. So I think any decision that binds the
>>> project going forwards should have a lazy consensus DISCUSS thread at least.
>>>
>>> I don’t think it needs to be burdensome though - trivial API changes
>>> could begin while the DISCUSS thread is underway, expecting they usually
>>> won’t raise a murmur.
>>>
>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>
>>>
>>> Came up this morning / afternoon in dev slack:
>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>
>>> The gist of it: we're lacking clarity on whether the expectation on the
>>> project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification
>>> or only on modifications where the author feels they are adjusting a
>>> paradigm / strategy for an API.
>>>
>>> The code style section on Public APIs is actually a little unclear:
>>> https://cassandra.apache.org/_/development/code_style.html
>>>
>>> Public APIs
>>>
>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>>
>>>
>>> My .02:
>>> 1. We should rename that page to a "code contribution guide" as
>>> discussed on the slack thread
>>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
>>> vtables, .java interfaces targeting user extension, etc) should hit the dev
>>> ML w/a [DISCUSS] thread.
>>>
>>> This takes the burden of trying to determine if a change is consistent
>>> w/existing strategy or not etc. off the author in isolation and allows devs
>>> to work concurrently on API changes w/out risk of someone else working on
>>> something that may inform their work or vice versa.
>>>
>>> We've learned that API's are *really really hard* to deprecate,
>>> disruptive to our users when we change or remove them, and can cause
>>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>>> discussions about JMX, etc. They're the definition of a "one-way-door"
>>> decision and represent a long-term maintenance burden commitment from the
>>> project.
>>>
>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>> quick consensus checks resolved via lazy consensus or after some slight
>>> discussion; ideally this wouldn't represent a huge burden of coordination
>>> on folks working on changes.
>>>
>>> So that's 1 opinion. What other opinions are out there?
>>>
>>> ~Josh
>>>
>>>
>>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Andrés de la Peña <ad...@apache.org>.
Indeed that contribution policy should be clearer and not be on a page
titled code style, thanks for briging that up.
If we consider all those things APIs, and additions are also considered
changes that require a DISCUSS thread, it turns out that almost any
not-bugfix ticket would require a mail list thread. In fact, if one goes
through CHANGES.txt it's easy to see that most entries would have required
a DISCUSS thread.
I think that such a strict policy would only make us lose agility and
increase the burden of almost any contribution. After all, it's not that
changes without a DISCUSS thread happen in secret. Changes are publicly
visible on their tickets, those tickets are notified on Slack so anyone can
jump into the ticket discussions and set themselves as reviewers, and
reviewers can ask for DISCUSS threads whenever they think more opinions or
broader consensus are needed.
Also, a previous DISCUSS thread is not going to impede that any changes are
going to be questioned later. We have seen changes that are proposed,
discussed and approved as CEPs, reviewed for weeks or months, and finally
committed, and still they are questioned shortly after that cycle, and
asked to be changed or discussed again. I don't think that an avalanche of
DISCUSS threads is going to improve that, since usually the problem is that
people don't have the time for deeply looking into the changes when they
are happening. I doubt that more notification channels are going to improve
that.
Of course I'm not saying that there should never DISCUSS threads before
starting a change. Probably we can all agree that major changes and things
that break compatibility would need previous discussion.
On Mon, 5 Dec 2022 at 10:16, Benjamin Lerer <bl...@apache.org> wrote:
> Thanks for opening this thread Josh,
>
> It seems perfectly normal to me that for important changes or questions we
> raise some discussion to the mailing list.
>
> My understanding of the current proposal implies that for the 4.1 release
> we should have had to raise over 70 discussion threads.
> We have a minimum of 2 commiters required for every patch. Should we not
> trust them to update nodetool, the virtual tables or other things on their
> own?
>
> There is already multiple existing ways to track changes in specific code
> areas. I am personaly tracking the areas in which I am the most involved
> this way and I know that a lot of people do the same.
>
> To be transparent, It is not clear to me what the underlying issue is? Do
> we have some specific cases that illustrate the underlying problem? Thrift
> and JMX are from a different time in my opinion.
>
> Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a
> écrit :
>
>> +1 to moving that into it's own section outside the coding style page.
>>
>> Dinesh I also thought in terms of backward compatibility here. But notice
>> the discussion is about _any change_ to the API such as adding new CQL
>> functions. Would adding or changing an exception type or a user warning
>> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
>> opening a DISCUSS for almost every ticket and sthg easy to miss.
>>
>> I wonder, you guys know the code better, if 'public APIs' could be
>> matched to a reasonable set of files (cql parsing, yaml, etc) and have
>> jenkins send an email when changes are detected on them. Overkill? bad
>> idea? :thinking:...
>> On 4/12/22 1:14, Dinesh Joshi wrote:
>>
>> We should also very clearly list out what is considered a public API. The
>> current statement that we have is insufficient:
>>
>> public APIs, including CQL, virtual tables, JMX, yaml, system
>> properties, etc.
>>
>>
>> The guidance on treatment of public APIs should also move out of "Code
>> Style" page as it isn't strictly related to code style. Backward
>> compatibility of public APIs is a best practice & project policy.
>>
>>
>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>
>> I think some of that text also got garbled by mixing up how you approach
>> internal APIs and external APIs. We should probably clarify that there are
>> different burdens for each. Which is all my fault as the formulator. I
>> remember it being much clearer in my head.
>>
>> My view is the same as yours Josh. Evolving the database’s public APIs is
>> something that needs community consensus. The more visibility these
>> decisions get, the better the final outcome (usually). Even small API
>> changes need to be carefully considered to ensure the API evolves
>> coherently, and this is particularly true for something as complex and
>> central as CQL.
>>
>> A DISCUSS thread is a good forcing function to think about what you’re
>> trying to achieve and why, and to provide others a chance to spot potential
>> flaws, alternatives and interactions with work you may not be aware of.
>>
>> It would be nice if there were an easy rubric for whether something needs
>> feedback, but I don’t think there is. One person’s obvious change may be
>> another’s obvious problem. So I think any decision that binds the project
>> going forwards should have a lazy consensus DISCUSS thread at least.
>>
>> I don’t think it needs to be burdensome though - trivial API changes
>> could begin while the DISCUSS thread is underway, expecting they usually
>> won’t raise a murmur.
>>
>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>
>>
>> Came up this morning / afternoon in dev slack:
>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>
>> The gist of it: we're lacking clarity on whether the expectation on the
>> project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification
>> or only on modifications where the author feels they are adjusting a
>> paradigm / strategy for an API.
>>
>> The code style section on Public APIs is actually a little unclear:
>> https://cassandra.apache.org/_/development/code_style.html
>>
>> Public APIs
>>
>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>>
>>
>> My .02:
>> 1. We should rename that page to a "code contribution guide" as discussed
>> on the slack thread
>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
>> vtables, .java interfaces targeting user extension, etc) should hit the dev
>> ML w/a [DISCUSS] thread.
>>
>> This takes the burden of trying to determine if a change is consistent
>> w/existing strategy or not etc. off the author in isolation and allows devs
>> to work concurrently on API changes w/out risk of someone else working on
>> something that may inform their work or vice versa.
>>
>> We've learned that API's are *really really hard* to deprecate,
>> disruptive to our users when we change or remove them, and can cause
>> serious pain and ecosystem fragmentation when changed. See: Thrift, current
>> discussions about JMX, etc. They're the definition of a "one-way-door"
>> decision and represent a long-term maintenance burden commitment from the
>> project.
>>
>> Lastly, I'd expect the vast majority of these discuss threads to be quick
>> consensus checks resolved via lazy consensus or after some slight
>> discussion; ideally this wouldn't represent a huge burden of coordination
>> on folks working on changes.
>>
>> So that's 1 opinion. What other opinions are out there?
>>
>> ~Josh
>>
>>
>>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benjamin Lerer <bl...@apache.org>.
Thanks for opening this thread Josh,
It seems perfectly normal to me that for important changes or questions we
raise some discussion to the mailing list.
My understanding of the current proposal implies that for the 4.1 release
we should have had to raise over 70 discussion threads.
We have a minimum of 2 commiters required for every patch. Should we not
trust them to update nodetool, the virtual tables or other things on their
own?
There is already multiple existing ways to track changes in specific code
areas. I am personaly tracking the areas in which I am the most involved
this way and I know that a lot of people do the same.
To be transparent, It is not clear to me what the underlying issue is? Do
we have some specific cases that illustrate the underlying problem? Thrift
and JMX are from a different time in my opinion.
Le lun. 5 déc. 2022 à 08:09, Berenguer Blasi <be...@gmail.com> a
écrit :
> +1 to moving that into it's own section outside the coding style page.
>
> Dinesh I also thought in terms of backward compatibility here. But notice
> the discussion is about _any change_ to the API such as adding new CQL
> functions. Would adding or changing an exception type or a user warning
> qualify for a DISCUSS thread also? I wonder if we're talking ourselves into
> opening a DISCUSS for almost every ticket and sthg easy to miss.
>
> I wonder, you guys know the code better, if 'public APIs' could be matched
> to a reasonable set of files (cql parsing, yaml, etc) and have jenkins send
> an email when changes are detected on them. Overkill? bad idea?
> :thinking:...
> On 4/12/22 1:14, Dinesh Joshi wrote:
>
> We should also very clearly list out what is considered a public API. The
> current statement that we have is insufficient:
>
> public APIs, including CQL, virtual tables, JMX, yaml, system
> properties, etc.
>
>
> The guidance on treatment of public APIs should also move out of "Code
> Style" page as it isn't strictly related to code style. Backward
> compatibility of public APIs is a best practice & project policy.
>
>
> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>
> I think some of that text also got garbled by mixing up how you approach
> internal APIs and external APIs. We should probably clarify that there are
> different burdens for each. Which is all my fault as the formulator. I
> remember it being much clearer in my head.
>
> My view is the same as yours Josh. Evolving the database’s public APIs is
> something that needs community consensus. The more visibility these
> decisions get, the better the final outcome (usually). Even small API
> changes need to be carefully considered to ensure the API evolves
> coherently, and this is particularly true for something as complex and
> central as CQL.
>
> A DISCUSS thread is a good forcing function to think about what you’re
> trying to achieve and why, and to provide others a chance to spot potential
> flaws, alternatives and interactions with work you may not be aware of.
>
> It would be nice if there were an easy rubric for whether something needs
> feedback, but I don’t think there is. One person’s obvious change may be
> another’s obvious problem. So I think any decision that binds the project
> going forwards should have a lazy consensus DISCUSS thread at least.
>
> I don’t think it needs to be burdensome though - trivial API changes could
> begin while the DISCUSS thread is underway, expecting they usually won’t
> raise a murmur.
>
> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>
>
> Came up this morning / afternoon in dev slack:
> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>
> The gist of it: we're lacking clarity on whether the expectation on the
> project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification
> or only on modifications where the author feels they are adjusting a
> paradigm / strategy for an API.
>
> The code style section on Public APIs is actually a little unclear:
> https://cassandra.apache.org/_/development/code_style.html
>
> Public APIs
>
> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>
>
> My .02:
> 1. We should rename that page to a "code contribution guide" as discussed
> on the slack thread
> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX,
> vtables, .java interfaces targeting user extension, etc) should hit the dev
> ML w/a [DISCUSS] thread.
>
> This takes the burden of trying to determine if a change is consistent
> w/existing strategy or not etc. off the author in isolation and allows devs
> to work concurrently on API changes w/out risk of someone else working on
> something that may inform their work or vice versa.
>
> We've learned that API's are *really really hard* to deprecate,
> disruptive to our users when we change or remove them, and can cause
> serious pain and ecosystem fragmentation when changed. See: Thrift, current
> discussions about JMX, etc. They're the definition of a "one-way-door"
> decision and represent a long-term maintenance burden commitment from the
> project.
>
> Lastly, I'd expect the vast majority of these discuss threads to be quick
> consensus checks resolved via lazy consensus or after some slight
> discussion; ideally this wouldn't represent a huge burden of coordination
> on folks working on changes.
>
> So that's 1 opinion. What other opinions are out there?
>
> ~Josh
>
>
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Berenguer Blasi <be...@gmail.com>.
+1 to moving that into it's own section outside the coding style page.
Dinesh I also thought in terms of backward compatibility here. But
notice the discussion is about _any change_ to the API such as adding
new CQL functions. Would adding or changing an exception type or a user
warning qualify for a DISCUSS thread also? I wonder if we're talking
ourselves into opening a DISCUSS for almost every ticket and sthg easy
to miss.
I wonder, you guys know the code better, if 'public APIs' could be
matched to a reasonable set of files (cql parsing, yaml, etc) and have
jenkins send an email when changes are detected on them. Overkill? bad
idea? :thinking:...
On 4/12/22 1:14, Dinesh Joshi wrote:
> We should also very clearly list out what is considered a public API.
> The current statement that we have is insufficient:
>
>> public APIs, including CQL, virtual tables, JMX, yaml, system
>> properties, etc.
>
> The guidance on treatment of public APIs should also move out of "Code
> Style" page as it isn't strictly related to code style. Backward
> compatibility of public APIs is a best practice & project policy.
>
>
>> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>>
>> I think some of that text also got garbled by mixing up how you
>> approach internal APIs and external APIs. We should probably clarify
>> that there are different burdens for each. Which is all my fault as
>> the formulator. I remember it being much clearer in my head.
>>
>> My view is the same as yours Josh. Evolving the database’s public
>> APIs is something that needs community consensus. The more visibility
>> these decisions get, the better the final outcome (usually). Even
>> small API changes need to be carefully considered to ensure the API
>> evolves coherently, and this is particularly true for something as
>> complex and central as CQL.
>>
>> A DISCUSS thread is a good forcing function to think about what
>> you’re trying to achieve and why, and to provide others a chance to
>> spot potential flaws, alternatives and interactions with work you may
>> not be aware of.
>>
>> It would be nice if there were an easy rubric for whether something
>> needs feedback, but I don’t think there is. One person’s obvious
>> change may be another’s obvious problem. So I think any decision that
>> binds the project going forwards should have a lazy consensus DISCUSS
>> thread at least.
>>
>> I don’t think it needs to be burdensome though - trivial API changes
>> could begin while the DISCUSS thread is underway, expecting they
>> usually won’t raise a murmur.
>>
>>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>>
>>>
>>> Came up this morning / afternoon in dev slack:
>>> https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>>>
>>> The gist of it: we're lacking clarity on whether the expectation on
>>> the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API
>>> modification or only on modifications where the author feels they
>>> are adjusting a paradigm / strategy for an API.
>>>
>>> The code style section on Public APIs is actually a little unclear:
>>> https://cassandra.apache.org/_/development/code_style.html
>>> <https://cassandra.apache.org/_/development/code_style.html>
>>>
>>>> Public APIs
>>>>
>>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought todev@cassandra.apache.org for discussion.
>>>
>>> My .02:
>>> 1. We should rename that page to a "code contribution guide" as
>>> discussed on the slack thread
>>> 2. *All* publicly facing API changes (tool output, CQL semantics,
>>> JMX, vtables, .java interfaces targeting user extension, etc) should
>>> hit the dev ML w/a [DISCUSS] thread.
>>>
>>> This takes the burden of trying to determine if a change is
>>> consistent w/existing strategy or not etc. off the author in
>>> isolation and allows devs to work concurrently on API changes w/out
>>> risk of someone else working on something that may inform their work
>>> or vice versa.
>>>
>>> We've learned that API's are /really really hard/ to deprecate,
>>> disruptive to our users when we change or remove them, and can cause
>>> serious pain and ecosystem fragmentation when changed. See: Thrift,
>>> current discussions about JMX, etc. They're the definition of a
>>> "one-way-door" decision and represent a long-term maintenance burden
>>> commitment from the project.
>>>
>>> Lastly, I'd expect the vast majority of these discuss threads to be
>>> quick consensus checks resolved via lazy consensus or after some
>>> slight discussion; ideally this wouldn't represent a huge burden of
>>> coordination on folks working on changes.
>>>
>>> So that's 1 opinion. What other opinions are out there?
>>>
>>> ~Josh
>
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Dinesh Joshi <dj...@apache.org>.
We should also very clearly list out what is considered a public API. The current statement that we have is insufficient:
> public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc.
The guidance on treatment of public APIs should also move out of "Code Style" page as it isn't strictly related to code style. Backward compatibility of public APIs is a best practice & project policy.
> On Dec 2, 2022, at 2:08 PM, Benedict <be...@apache.org> wrote:
>
> I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
>
> My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
>
> A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
>
> It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
>
> I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
>
>> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>>
>>
>> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189 <https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189>
>>
>> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>>
>> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html <https://cassandra.apache.org/_/development/code_style.html>
>>
>>> Public APIs
>>>
>>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org <ma...@cassandra.apache.org> for discussion.
>>
>> My .02:
>> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
>> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>>
>> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>>
>> We've learned that API's are really really hard to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>>
>> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>>
>> So that's 1 opinion. What other opinions are out there?
>>
>> ~Josh
Re: [DISCUSS] API modifications and when to raise a thread on the dev ML
Posted by Benedict <be...@apache.org>.
I think some of that text also got garbled by mixing up how you approach internal APIs and external APIs. We should probably clarify that there are different burdens for each. Which is all my fault as the formulator. I remember it being much clearer in my head.
My view is the same as yours Josh. Evolving the database’s public APIs is something that needs community consensus. The more visibility these decisions get, the better the final outcome (usually). Even small API changes need to be carefully considered to ensure the API evolves coherently, and this is particularly true for something as complex and central as CQL.
A DISCUSS thread is a good forcing function to think about what you’re trying to achieve and why, and to provide others a chance to spot potential flaws, alternatives and interactions with work you may not be aware of.
It would be nice if there were an easy rubric for whether something needs feedback, but I don’t think there is. One person’s obvious change may be another’s obvious problem. So I think any decision that binds the project going forwards should have a lazy consensus DISCUSS thread at least.
I don’t think it needs to be burdensome though - trivial API changes could begin while the DISCUSS thread is underway, expecting they usually won’t raise a murmur.
> On 2 Dec 2022, at 19:25, Josh McKenzie <jm...@apache.org> wrote:
>
>
> Came up this morning / afternoon in dev slack: https://the-asf.slack.com/archives/CK23JSY2K/p1669981168190189
>
> The gist of it: we're lacking clarity on whether the expectation on the project is to hit the dev ML w/a [DISCUSS] thread on _any_ API modification or only on modifications where the author feels they are adjusting a paradigm / strategy for an API.
>
> The code style section on Public APIs is actually a little unclear: https://cassandra.apache.org/_/development/code_style.html
>
>> Public APIs
>>
>> These considerations are especially important for public APIs, including CQL, virtual tables, JMX, yaml, system properties, etc. Any planned additions must be carefully considered in the context of any existing APIs. Where possible the approach of any existing API should be followed. Where the existing API is poorly suited, a strategy should be developed to modify or replace the existing API with one that is more coherent in light of the changes - which should also carefully consider any planned or expected future changes to minimise churn. Any strategy for modifying APIs should be brought to dev@cassandra.apache.org for discussion.
>
> My .02:
> 1. We should rename that page to a "code contribution guide" as discussed on the slack thread
> 2. *All* publicly facing API changes (tool output, CQL semantics, JMX, vtables, .java interfaces targeting user extension, etc) should hit the dev ML w/a [DISCUSS] thread.
>
> This takes the burden of trying to determine if a change is consistent w/existing strategy or not etc. off the author in isolation and allows devs to work concurrently on API changes w/out risk of someone else working on something that may inform their work or vice versa.
>
> We've learned that API's are really really hard to deprecate, disruptive to our users when we change or remove them, and can cause serious pain and ecosystem fragmentation when changed. See: Thrift, current discussions about JMX, etc. They're the definition of a "one-way-door" decision and represent a long-term maintenance burden commitment from the project.
>
> Lastly, I'd expect the vast majority of these discuss threads to be quick consensus checks resolved via lazy consensus or after some slight discussion; ideally this wouldn't represent a huge burden of coordination on folks working on changes.
>
> So that's 1 opinion. What other opinions are out there?
>
> ~Josh