+1 This is the same we do in BookKeeper but for the docs in general (not only API) but the concept is the same. In BookKeeper we only have one doc version per minor. https://bookkeeper.apache.org/releases If a patch introduces a change for some reason (likely security reasons) the rule is to explicitly highlight that it does apply beginning from the patched release.
The other main benefit is for the users since there are not tons of releases and the UX is actually smoother. Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu <y...@streamnative.io.invalid> ha scritto: > +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 >
