+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 <bened...@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 <jmcken...@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 to...@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
