> > The root cause is that we don't have an API abstraction for the > pulsar-broker module
+1 I think that's reasonable to think about the pulsar-broker module as internal and to not take care of retrocompatibility. If we have the desire to expose the broker service classes in a compatible way, we'll need to provide abstracted APIs for that. Applications that embed the pulsar-broker dependency should be aware that signatures may change even in patch releases and there's no compatibility guarantee. Do we explain to users how to add the broker dependency in the doc? If so, we could add a note there. Nicolò Boschi Il giorno mer 7 dic 2022 alle ore 09:08 Haiting Jiang < jianghait...@gmail.com> ha scritto: > Hi all, > > We already have working procedures to change the public API, like PIP > , mail-discussion and the PR templates. > From what I understand, the problem is more like how to provide a > clear and proper definition of "Broker Public API". > I believe it's the reason why PIP-136 updated the method signature and > no one finds it until now. > > And if we put the scope of "public API" to all the public methods in > the broker modules, it would be definitely too broad and slow our > development of other features. > > Thanks, > Haiting > > On Wed, Dec 7, 2022 at 1:50 PM <mattisonc...@gmail.com> wrote: > > > > > I'm afraid it's very hard to avoid these API changes. Take theprotocol > handler as example, it could make use of nearly all modulesvia the > `PulsarService` object. The cost to keep the compatibilitymight be high so > that much legacy code could be left. For example,each time a new argument > is added to a method, we have to add anoverload to keep the compatibility. > It could be confusing to peoplewho don't know these extensions and they > might wonder why an overloadis needed that is never used in the Pulsar's > main repo. > > Yes, I totally agree with your point. it's a trade-off, I think we can > hold this discussion until the ecosystem becomes bigger and this problem > becomes more prominent. > > > > Best, > > Mattison > > > > On Dec 7, 2022, 13:37 +0800, Yunze Xu <y...@streamnative.io.invalid>, > wrote: > > > I'm afraid it's very hard to avoid these API changes. Take the > > > protocol handler as example, it could make use of nearly all modules > > > via the `PulsarService` object. The cost to keep the compatibility > > > might be high so that much legacy code could be left. For example, > > > each time a new argument is added to a method, we have to add an > > > overload to keep the compatibility. It could be confusing to people > > > who don't know these extensions and they might wonder why an overload > > > is needed that is never used in the Pulsar's main repo. > > > > > > The root cause is that we don't have an API abstraction for the > > > pulsar-broker module, like the pulsar-client-api module to the > > > pulsar-client mode. But it could be a huge project to add something > > > like pulsar-broker-api. > > > > > > Thanks, > > > Yunze > > > > > > On Wed, Dec 7, 2022 at 1:21 PM <mattisonc...@gmail.com> wrote: > > > > > > > > > > It would help me understand if you would explain how apis were > changed in this PR > > > > Sorry, I explained above. it's a small break, maybe it just breaks > some unit test mock, but it can be used as an example. > > > > > > We should be sure to track and then highlight API changes in > release documents. > > > > > > API changes should be held until the next major version (now > 2.12) and be documented with that release. > > > > > > I think we need to be explicit in our GitHub PR template. I > don’t have a suggested edit yet, but the idea is to add text about > > > > > > 1. How the PR changes the API2. Which PIP authorizes it > > > > +1 for an awesome idea. > > > > > > > > Am I just wondering if we can avoid breaking it? maybe we can give > the old method a @Deprecated? > > > > > > > > Best, > > > > Mattison > > > > On Dec 7, 2022, 12:56 +0800, Dave Fisher <wave4d...@comcast.net>, > wrote: > > > > > > We should be sure to track and then highlight API changes in > release documents. API changes should be held until the next major version > (now 2.12) and be documented with that release. I think we need to be > explicit in our GitHub PR template. I don’t have a suggested edit yet, but > the idea is to add text about 1. How the PR changes the API 2. Which PIP > authorizes it >
