Hi All,
I don't think we can be 100% prescriptive here. There will always be
gray areas on where API changes start or end. Even on what is an API
change and discussions about why a change was forgotten, not
communicated, etc. I think we should rely on people's judgement on when
to hit the ML/
I’m inclined to agree with Jeremiah and Patrick, even if it might be a steep jump from what we’ve been used to. CQL needs to be treated with the utmost care and attention to detail. Would we apply the same standard to semantic bug fixes too? Perhaps we should, where there isn’t an urgent timeline a
> if a patch adds, say, a single JMX method to expose the
> metric, having an ML thread for it may seem redundant
My fear is someone missing that there's an idiom or pattern within the codebase
for metrics they miss then we end up with inconsistent metric names / groups
exposed to users.
Especia
Hello everyone,
I would say that having a CEP and a well-defined set of major public
API changes is a must, and the corresponding discussion of CEP is also
well-defined here [1]. This ensures that we do not miss any important
changes. Everything related to the public API is also described in the
I think we need a DISCUSS thread at minimum for API changes. And for anything
changing CQL syntax, I think a CEP is warranted. Even if it is only a small
change to the syntax.
> On Feb 2, 2023, at 9:32 AM, Patrick McFadin wrote:
>
> API changes are near and dear to my world. The scope of cha
API changes are near and dear to my world. The scope of changes could be
minor or major, so I think B is the right way forward.
Not to throw off the momentum, but could this even warrant a separate CEP
in some cases? For example, CEP-15 is a huge change, but the CQL syntax
will continuously evolve
Things I think of as API's:
1. nodetool output (user tooling couples with this)
2. CQL syntax
3. JMX
4. VTables
5. Potential future refactored and deliberately exposed API interfaces
(SSTables, custom indexes, etc)
API's persist; I don't think lazy consensus to favor velocity is the right
tradeo
“ Only that it locks out of the conversation anyone without a Jira login”
Very valid point I forgot about - since recently people need invitation in
order to create account…
Then I would say C until we clarify the scope. Thanks
On Thu, 2 Feb 2023 at 8:54, Benedict wrote:
> I think lazy consensus
I think lazy consensus is fine for all of these things. If a DISCUSS thread is crickets, or just positive responses, then definitely it can proceed without further ceremony.I think “with heads-up to the mailing list” is very close to B? Only that it locks out of the conversation anyone without a Ji
While I do agree with you, I am thinking that if we include many things
that we would expect lazy consensus on I would probably have different
preference.
I definitely don’t mean to stall this though so in that case:
I’d say combination of A+C (jira with heads up on the ML if someone is
interested
I think it’s fine to separate the systems from the policy? We are agreeing a policy for systems we want to make guarantees about to our users (regarding maintenance and compatibility)For me, this is (at minimum) CQL and virtual tables. But I don’t think the policy differs based on the contents of t
“ So we can close out this discussion, let’s assume we’re only discussing
any interfaces we want to make promises for. We can have a separate
discussion about which those are if there is any disagreement.”
May I suggest we first clear this topic and then move to voting? I would
say I see confusion,
Bringing light to new proposed APIs no less important - if not more, for
reasons already mentioned in this thread. For it’s not easy to change them
later.
Voting B.
> On 2 Feb 2023, at 10:15, Andrés de la Peña wrote:
>
> If it's a breaking change, like removing a method or property, I think w
If we expose internal mechanics to public APIs, we should probably document what our promises are - ie none, even between patch versions.So we can close out this discussion, let’s assume we’re only discussing any interfaces we want to make promises for. We can have a separate discussion about which
I guess that depends on the type of change, and what we consider an API.
If it's a breaking change, like removing a method or property, I think we
would need a DISCUSS API thread prior to making changes. However, if the
change is an addition, like adding a new yaml property or a JMX method, I
thin
Closing the loop on seeking consensus for UX/UI/API changes, I see a few
options. Can we rank choice vote please?
A - Jira suffices
B - Post a DISCUSS API thread prior to making changes
C - Periodically publish a list of API changes for retrospective consideration
by the community
Points raise
>
> 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 ear
> 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
>
> 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 t
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
dis
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
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 introd
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 ?
> 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
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
>
> 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
> 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 understandin
>
> 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 se
“ 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-
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 n
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 e
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.
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 suggestio
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 maintain
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 l
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 m
+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 qualif
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
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
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 au
40 matches
Mail list logo
