+1. We should never introduce API changes in minor releases. Though there were some exceptional cases where new APIs were added into C++ clients as a catch-up, which might be caused by the slowness of a major release. But we should avoid it because the C++ clients are separated now.
Thanks, Yunze On Fri, Nov 25, 2022 at 5:08 PM tison <wander4...@gmail.com> wrote: > > Hi, > > I'm working on the API docs generator tools and noticed that we're > inconsistently releasing API docs for Python client, C++ client, Java > client, admin and functions. > > Basically, we release API docs _sometimes_ for minor release (patch version > bump), and display API docs with -SNAPSHOT suffix for javadocs and C++ > client API doc. > > I finished the tools to generate API docs upon a specific X.Y.Z version and > remove all SNAPSHOT docs for C++ client API docs. > > Although, with a few offline discussion with RMs (@Yunze, @Haiting), I > realize that as long as patch versions don't change public API, the API > docs should be the same among the same series of major version (e.g., > 2.8.x, 3.0.x). > > Thus, I propose to release API docs only for major release (a.k.a, minor > version bump). > > I'm going to: > > 1. Adjust the tools[1] to accept X.Y.Z version and produce API docs for X.Y; > 2. Adjust references in the doc site to X.Y API docs (current to X.Y.Z or > -SNAPSHOT); > 3. Update the release process to explicitly document RM's responsibility > and how-tos. > > All these changes are supposed to be applied for maintained versions: >= > 2.8. Existing links except -SNAPSHOT ones will be kept. > > What do you think? > > Best, > tison. > > [1] https://github.com/apache/pulsar-site/blob/main/tools/pytools/README.md
