On 1/5/23 15:24, Han Zhou wrote:
On Thu, Jan 5, 2023 at 12:13 PM Mark Michelson <[email protected]
<mailto:[email protected]>> wrote:
>
> On 1/5/23 02:36, Han Zhou wrote:
> >
> >
> > On Thu, Dec 29, 2022 at 7:20 AM Igor Zhukov <[email protected]
<mailto:[email protected]>
> > <mailto:[email protected] <mailto:[email protected]>>> wrote:
> > >
> > > From: Igor Zhukov <[email protected]
<mailto:[email protected]> <mailto:[email protected]
<mailto:[email protected]>>>
> > >
> > > Found at
https://docs.ovn.org/en/latest/internals/maintainers.html
<https://docs.ovn.org/en/latest/internals/maintainers.html>
> > <https://docs.ovn.org/en/latest/internals/maintainers.html
<https://docs.ovn.org/en/latest/internals/maintainers.html>>
> > >
> > > Signed-off-by: Igor Zhukov <[email protected]
<mailto:[email protected]>
> > <mailto:[email protected] <mailto:[email protected]>>>
> > >
> > > ---
> > > MAINTAINERS.rst | 6 +++---
> > > 1 file changed, 3 insertions(+), 3 deletions(-)
> > >
> > > diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst
> > > index a4012a5cf..adb4ffca2 100644
> > > --- a/MAINTAINERS.rst
> > > +++ b/MAINTAINERS.rst
> > > @@ -29,10 +29,10 @@ OVN committers are the people who have been
> > granted access to push
> > > changes to to the OVN git repository.
> > >
> > > The responsibilities of an OVN committer are documented
> > > -`here <Documentation/internals/committer-responsibilities.rst>`__.
> > > +:doc:`committer-responsibilities`.
> > >
> > > The process for adding or removing committers is documented
> > > -`here <Documentation/internals/committer-grant-revocation.rst>`__.
> > > +:doc:`committer-grant-revocation`.
> > >
> > > This is the current list of active OVN committers:
> > >
> > > @@ -60,7 +60,7 @@ This is the current list of active OVN committers:
> > >
> > > The project also maintains a list of Emeritus Committers (or
> > Maintainers).
> > > More information about Emeritus Committers can be found
> > > -`here <Documentation/internals/committer-emeritus-status.rst>`__.
> > > +:doc:`committer-emeritus-status`.
> > >
> > > .. list-table:: OVS Emeritus Maintainers
> > > :header-rows: 0
> > > --
> > > 2.34.1
> > >
> > > _______________________________________________
> > > dev mailing list
> > > [email protected] <mailto:[email protected]>
<mailto:[email protected] <mailto:[email protected]>>
> > > https://mail.openvswitch.org/mailman/listinfo/ovs-dev
<https://mail.openvswitch.org/mailman/listinfo/ovs-dev>
> > <https://mail.openvswitch.org/mailman/listinfo/ovs-dev
<https://mail.openvswitch.org/mailman/listinfo/ovs-dev>>
> >
> > Hi Igor,
> >
> > Thanks for fixing. However, here is a dilemma. The :doc: extension
> > doesn't work on github, so for root level documents it is not
> > recommended to be used, as mentioned at:
> >
> >
https://docs.ovn.org/en/latest/internals/contributing/documentation-style.html#restructuredtext-vs-sphinx <https://docs.ovn.org/en/latest/internals/contributing/documentation-style.html#restructuredtext-vs-sphinx> <https://docs.ovn.org/en/latest/internals/contributing/documentation-style.html#restructuredtext-vs-sphinx <https://docs.ovn.org/en/latest/internals/contributing/documentation-style.html#restructuredtext-vs-sphinx>>
> >
> > The MAINTAINERS.rst is a root level document but it is included by the
> > Documents/internals/maintainers.rst. The current format works well on
> > github:
> >
> > https://github.com/ovn-org/ovn/blob/main/MAINTAINERS.rst
<https://github.com/ovn-org/ovn/blob/main/MAINTAINERS.rst>
> > <https://github.com/ovn-org/ovn/blob/main/MAINTAINERS.rst
<https://github.com/ovn-org/ovn/blob/main/MAINTAINERS.rst>>
> >
> > So, I don't have a good solution to make both work. One idea is
probably
> > to include both types of links in the document, but it would make both
> > versions look weird.
> > Another idea may be, just remove the
Documents/internals/maintainers.rst.
> > What do you think?
> > @Mark Michelson <mailto:[email protected]
<mailto:[email protected]>>@Numan Siddique
> > <mailto:[email protected] <mailto:[email protected]>>@Dumitru Ceara
<mailto:[email protected] <mailto:[email protected]>>
> >
> > Thanks,
> > Han
>
> Hi Han,
>
> I want to make sure I understand the results of removing
> Documents/internals/maintainers.rst . On github, everything would still
> work as intended. The MAINTAINERS.rst root-level file links will link
> into the Documentation directory as intended. However, on
docs.ovn.org <http://docs.ovn.org>,
> there would no longer be a "Committers" link in the "OVN Internals"
section.
>
> I guess the question to answer is how common it is for people to want to
> find the maintainers using docs.ovn.org <http://docs.ovn.org> vs
github.com <http://github.com>. I would suspect
> that people mostly go to docs.ovn.org <http://docs.ovn.org> to learn
how to use OVN and read
> user documentation, and people wishing to contact maintainers would more
> likely look on github. Removing Documentation/internals/maintainers.rst
> would probably be fine.
>
> If we really wanted to have maintainers listed in both places, then we
> could go with Igor's suggestion of duplicating the documents. As he
> pointed out, this would mean having to update two places every time the
> maintainers list changes. I just know we would mess this up at some
> point, so I'd rather not do this.
>
> A different way to go would be to make MAINTAINERS.rst be just the bare
> tables of maintainers, and keep all of the links/explanations in
> Documentation/internals/maintainers.rst . I've experimented a bit here:
>
https://github.com/putnopvut/ovn/commit/36c20ddffc18c0734ea0b18dba070b746fa6ef41 <https://github.com/putnopvut/ovn/commit/36c20ddffc18c0734ea0b18dba070b746fa6ef41>
> . I haven't tested it, so it might not actually work or might look
> completely weird. But the gist should hopefully be clear, and if there
> are errors, they should be fixable.
>
> Mark Michelson
>
Thanks Mark for the inputs and experimentations. I am ok with your
approach, but IMHO, it would be nice to keep the basic descriptions and
links in the root level MAINTAINERS document. @Ilya Maximets
<mailto:[email protected]> proposed an approach to make the links work
in both documents. Please see his reply to this thread. I think that's
the best way so far. And I requested him to post a patch for OVN
(similar to his OVS patch).
I agree that Ilya's is much better thought-out than my approach. It
looks like it's using some context-dependent text replacement, which is
exactly the right approach to take if possible.
Regards,
Han
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
