Hi community, I'd like to bring back the discussion again since a similar discussion happened long ago [1].
Currently, there is no clear definition for the maintain strategy of public APIs. To make it more clear, I mean "public interface methods" and "public class methods" when I mentioned "public APIs".It's very ambiguous if it's acceptable to modify the method signature. Here are some examples: - Public APIs in pulsar-broker or pulsar-broker-common could be used in the protocol handlers - Public APIs in pulsar-client could be used due to the lack of control in pulsar-client-api like MessageId and PulsarClient However, we should not encourage users to leverage such APIs, which are mostly used internally. If authors use these APIs, they should be responsible to modify the code if a new release changed such APIs. See concrete examples here [2]. Therefore, I suggest adding the API signature guarantee somewhere (as a PIP or on the website). Here are my proposals. For any existing public method, no matter if it's from an interface or a class, - If it's in one module of pulsar-client-api, pulsar-common, pulsar-broker-common, should not be modified until the next LTS release (e.g. 4.0.0). Before that, it can only be marked as deprecated. - Otherwise, it can be modified in the next feature release (e.g. 3.3.0) - Specifically, for patch releases (e.g. 3.2.1), it needs public discussion in the mail list to be cherry-picked The strategy above is more relaxed than my previous proposal [1]. It tells ecosystem developers: - What are the public APIs - Use public APIs whenever possible - It's okay to use internal APIs if existing public APIs cannot satisfy their demands - Propose new public APIs if they think their demands are universals and then they won't risk modifying the code for new releases [1] https://lists.apache.org/thread/87n22qskcnpb0x44bfjy1chgdxzh8tf9 [2] https://github.com/apache/pulsar/pull/22182#discussion_r1531754956 Thanks, Yunze
