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 >
