Hi Tison, Great work.
One more item should be added to this list. Old api links like p.a.o/api/client/org/… should rewrite to the current main version like p.a.o/api/client/2.10.x/org/… What do you think? It may be tricky to write … Regards, Dave > On Dec 2, 2022, at 2:29 AM, tison <wander4...@gmail.com> wrote: > > All tasks except updating release notes have been done. You may take a look > to see if it meets your expectations. > > Best, > tison. > > > tison <wander4...@gmail.com> 于2022年12月1日周四 16:22写道： > >> 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 >>>>> >>>> >>>
