+1 Thanks, Haiting
On Fri, Nov 25, 2022 at 5:37 PM Nicolò Boschi <boschi1...@gmail.com> wrote: > > +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 > >
