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 >> <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 <mailto: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
