Filed issue: https://github.com/apache/pulsar/issues/18693
Best, tison. tison <wander4...@gmail.com> 于2022年12月1日周四 15:04写道： > > 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 >> > >> >
