You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by tison <wa...@gmail.com> on 2022/11/25 09:07:35 UTC
[DISCUSS] Release API docs only for major release (minor version bump)
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
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by tison <wa...@gmail.com>.
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 <wa...@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 <wa...@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 <wa...@gmail.com> 于2022年12月1日周四 16:22写道：
> >
> >> Filed issue: https://github.com/apache/pulsar/issues/18693
> >>
> >> Best,
> >> tison.
> >>
> >>
> >> tison <wa...@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 <mm...@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 <wa...@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 <wa...@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
> >>>>>
> >>>>
> >>>
>
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Dave Fisher <wa...@apache.org>.
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 <wa...@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 <wa...@gmail.com> 于2022年12月1日周四 16:22写道：
>
>> Filed issue: https://github.com/apache/pulsar/issues/18693
>>
>> Best,
>> tison.
>>
>>
>> tison <wa...@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 <mm...@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 <wa...@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 <wa...@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
>>>>>
>>>>
>>>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by tison <wa...@gmail.com>.
All tasks except updating release notes have been done. You may take a look
to see if it meets your expectations.
Best,
tison.
tison <wa...@gmail.com> 于2022年12月1日周四 16:22写道：
> Filed issue: https://github.com/apache/pulsar/issues/18693
>
> Best,
> tison.
>
>
> tison <wa...@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 <mm...@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 <wa...@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 <wa...@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
>>> >
>>>
>>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by tison <wa...@gmail.com>.
Filed issue: https://github.com/apache/pulsar/issues/18693
Best,
tison.
tison <wa...@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 <mm...@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 <wa...@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 <wa...@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
>> >
>>
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by tison <wa...@gmail.com>.
> 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 <mm...@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 <wa...@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 <wa...@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
> >
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Michael Marshall <mm...@apache.org>.
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 <wa...@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 <wa...@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
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Dave Fisher <wa...@comcast.net>.
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 <wa...@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
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by PengHui Li <co...@gmail.com>.
+1
Penghui
> On Nov 26, 2022, at 19:05, Enrico Olivelli <eo...@gmail.com> wrote:
>
> +1
>
> Thanks
> Enrico
>
> Il Sab 26 Nov 2022, 10:02 tison <wa...@gmail.com> ha scritto:
>
>> Thanks for your feedback! I'll create a tracking issue and start working on
>> subtasks the next week :)
>>
>> Best,
>> tison.
>>
>>
>> Haiting Jiang <ji...@gmail.com> 于2022年11月26日周六 14:43写道：
>>
>>> +1
>>>
>>> Thanks,
>>> Haiting
>>>
>>> On Fri, Nov 25, 2022 at 5:37 PM Nicolò Boschi <bo...@gmail.com>
>>> wrote:
>>>>
>>>> +1
>>>> This is the same we do in BookKeeper but for the docs in general (not
>>> only
>>>> API) but the concept is the same.
>>>> In BookKeeper we only have one doc version per minor.
>>>> https://bookkeeper.apache.org/releases
>>>> If a patch introduces a change for some reason (likely security
>> reasons)
>>>> the rule is to explicitly highlight that it does apply beginning from
>> the
>>>> patched release.
>>>>
>>>> The other main benefit is for the users since there are not tons of
>>>> releases and the UX is actually smoother.
>>>>
>>>>
>>>> Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu
>>>> <yz...@streamnative.io.invalid> ha scritto:
>>>>
>>>>> +1. We should never introduce API changes in minor releases. Though
>>>>> there were some exceptional cases where new APIs were added into C++
>>>>> clients as a catch-up, which might be caused by the slowness of a
>>>>> major release. But we should avoid it because the C++ clients are
>>>>> separated now.
>>>>>
>>>>> Thanks,
>>>>> Yunze
>>>>>
>>>>> On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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
>>>>>
>>>
>>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Enrico Olivelli <eo...@gmail.com>.
+1
Thanks
Enrico
Il Sab 26 Nov 2022, 10:02 tison <wa...@gmail.com> ha scritto:
> Thanks for your feedback! I'll create a tracking issue and start working on
> subtasks the next week :)
>
> Best,
> tison.
>
>
> Haiting Jiang <ji...@gmail.com> 于2022年11月26日周六 14:43写道：
>
> > +1
> >
> > Thanks,
> > Haiting
> >
> > On Fri, Nov 25, 2022 at 5:37 PM Nicolò Boschi <bo...@gmail.com>
> > wrote:
> > >
> > > +1
> > > This is the same we do in BookKeeper but for the docs in general (not
> > only
> > > API) but the concept is the same.
> > > In BookKeeper we only have one doc version per minor.
> > > https://bookkeeper.apache.org/releases
> > > If a patch introduces a change for some reason (likely security
> reasons)
> > > the rule is to explicitly highlight that it does apply beginning from
> the
> > > patched release.
> > >
> > > The other main benefit is for the users since there are not tons of
> > > releases and the UX is actually smoother.
> > >
> > >
> > > Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu
> > > <yz...@streamnative.io.invalid> ha scritto:
> > >
> > > > +1. We should never introduce API changes in minor releases. Though
> > > > there were some exceptional cases where new APIs were added into C++
> > > > clients as a catch-up, which might be caused by the slowness of a
> > > > major release. But we should avoid it because the C++ clients are
> > > > separated now.
> > > >
> > > > Thanks,
> > > > Yunze
> > > >
> > > > On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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
> > > >
> >
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by tison <wa...@gmail.com>.
Thanks for your feedback! I'll create a tracking issue and start working on
subtasks the next week :)
Best,
tison.
Haiting Jiang <ji...@gmail.com> 于2022年11月26日周六 14:43写道：
> +1
>
> Thanks,
> Haiting
>
> On Fri, Nov 25, 2022 at 5:37 PM Nicolò Boschi <bo...@gmail.com>
> wrote:
> >
> > +1
> > This is the same we do in BookKeeper but for the docs in general (not
> only
> > API) but the concept is the same.
> > In BookKeeper we only have one doc version per minor.
> > https://bookkeeper.apache.org/releases
> > If a patch introduces a change for some reason (likely security reasons)
> > the rule is to explicitly highlight that it does apply beginning from the
> > patched release.
> >
> > The other main benefit is for the users since there are not tons of
> > releases and the UX is actually smoother.
> >
> >
> > Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu
> > <yz...@streamnative.io.invalid> ha scritto:
> >
> > > +1. We should never introduce API changes in minor releases. Though
> > > there were some exceptional cases where new APIs were added into C++
> > > clients as a catch-up, which might be caused by the slowness of a
> > > major release. But we should avoid it because the C++ clients are
> > > separated now.
> > >
> > > Thanks,
> > > Yunze
> > >
> > > On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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
> > >
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Haiting Jiang <ji...@gmail.com>.
+1
Thanks,
Haiting
On Fri, Nov 25, 2022 at 5:37 PM Nicolò Boschi <bo...@gmail.com> wrote:
>
> +1
> This is the same we do in BookKeeper but for the docs in general (not only
> API) but the concept is the same.
> In BookKeeper we only have one doc version per minor.
> https://bookkeeper.apache.org/releases
> If a patch introduces a change for some reason (likely security reasons)
> the rule is to explicitly highlight that it does apply beginning from the
> patched release.
>
> The other main benefit is for the users since there are not tons of
> releases and the UX is actually smoother.
>
>
> Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu
> <yz...@streamnative.io.invalid> ha scritto:
>
> > +1. We should never introduce API changes in minor releases. Though
> > there were some exceptional cases where new APIs were added into C++
> > clients as a catch-up, which might be caused by the slowness of a
> > major release. But we should avoid it because the C++ clients are
> > separated now.
> >
> > Thanks,
> > Yunze
> >
> > On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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
> >
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Nicolò Boschi <bo...@gmail.com>.
+1
This is the same we do in BookKeeper but for the docs in general (not only
API) but the concept is the same.
In BookKeeper we only have one doc version per minor.
https://bookkeeper.apache.org/releases
If a patch introduces a change for some reason (likely security reasons)
the rule is to explicitly highlight that it does apply beginning from the
patched release.
The other main benefit is for the users since there are not tons of
releases and the UX is actually smoother.
Il giorno ven 25 nov 2022 alle ore 10:15 Yunze Xu
<yz...@streamnative.io.invalid> ha scritto:
> +1. We should never introduce API changes in minor releases. Though
> there were some exceptional cases where new APIs were added into C++
> clients as a catch-up, which might be caused by the slowness of a
> major release. But we should avoid it because the C++ clients are
> separated now.
>
> Thanks,
> Yunze
>
> On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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
>
Re: [DISCUSS] Release API docs only for major release (minor version bump)
Posted by Yunze Xu <yz...@streamnative.io.INVALID>.
+1. We should never introduce API changes in minor releases. Though
there were some exceptional cases where new APIs were added into C++
clients as a catch-up, which might be caused by the slowness of a
major release. But we should avoid it because the C++ clients are
separated now.
Thanks,
Yunze
On Fri, Nov 25, 2022 at 5:08 PM tison <wa...@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