Hi Dave, Thanks for your input! File an issue: https://github.com/apache/pulsar/issues/18725
Please take a look and see whether it's a real-world issue. If there are no user complaints, I think it's OK to have only versioned API docs links. Best, tison. Dave Fisher <w...@apache.org> 于2022年12月3日周六 00:32写道： > 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 > >>>>> > >>>> > >>> > >
