Thanks for your feedback! I'll create a tracking issue and start working on subtasks the next week :)
Best, tison. Haiting Jiang <jianghait...@gmail.com> 于2022年11月26日周六 14:43写道： > +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 > > > >
