> 2.10.X Good point. For consistency, now I tend to use 2.10.X instead. Said the reference page follows the same rule. I personally prefer X.Y but it's not a strong insistent and it's more complex to change current conventions.
> We can also remove the hosted broker api docs OK. I think it's about removing directly from the asf-site-next branch. I'll do it on the fly when touching related files. Best, tison. Michael Marshall <mmarsh...@apache.org> 于2022年11月29日周二 05:31写道： > Thanks for pushing this work forward, Tison. > > I agree with your proposed changes. > > > 1. Adjust the tools[1] to accept X.Y.Z version and produce API docs for > X.Y; > > I prefer the X.Y as you propose, but it might be confusing since it > doesn't align with our current paradigm where we use version "2.10.X" > for the 2.10 release line. > > 2. Adjust references in the doc site to X.Y API docs (current to X.Y.Z or > -SNAPSHOT); > > This will be helpful. > > 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. > > Makes sense to me. We can also remove the hosted broker api docs. I > proposed that here, > https://lists.apache.org/thread/rfrh7wxzlrk6mtd58xmnbqvph13895k6, but > I wasn't able to follow through with that work. > > When cleaning up, also note that some old javadocs were put in the > root of this directory: https://pulsar.apache.org/api/client/. When I > spent some time on the docs this summer, those files were actually > referenced in the website, so we'll need to update links before > removing them. > > Thanks, > Michael > > On Sun, Nov 27, 2022 at 8:30 PM Dave Fisher <wave4d...@comcast.net> wrote: > > > > Michael has brought this up before. Thanks for taking action! > > > > +1 > > > > Also I think we need to think about docs for versions including master > the same way, > > > > Best, > > Dave > > > > Sent from my iPhone > > > > > On Nov 25, 2022, at 1:08 AM, 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 > > >
