Re: [DISCUSS] API modifications and when to raise a thread on the dev ML

[Benedict]

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 those are if there is any disagreement. On 2 Feb 2023, at 10:16, Andrés de la Peña <adelap...@apache.org> wrote:  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 think JIRA suffices. As for what we consider a public API, we usually include extensible interfaces on this. For example, we can agree that the Index interface for secondary indexes is a public API. However, that interface exposes many other interfaces and classes through its methods. For example, that Index interface exposes ColumnFamillyStore, SSTableReader, ColumnMetadata, AbstractType, PartitionUpdate, etc. Changes into those indirectly exposed classes can easily break custom index implementations out there. Should we consider them public APIs too, and require a DISCUSS thread for every change on them? Should that include new methods that wouldn't break compatibility? On Thu, 2 Feb 2023 at 09:29, Benedict Elliott Smith <bened...@apache.org> wrote: 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 raised in the discussion included: lowering the bar for participation and avoiding unnecessary burden to developers. I vote B (only) because I think broader participation is most important for these topics. On 7 Dec 2022, at 15:43, Mick Semb Wever <m...@apache.org> wrote: 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.