On Thu, Jan 5, 2023 at 12:13 PM Mark Michelson <[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]>> wrote: > > > > > > From: Igor Zhukov <[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> > > > > > > Signed-off-by: Igor Zhukov <[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]> > > > 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 > > > > > 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> > > > > 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]>@Numan Siddique > > <mailto:[email protected]>@Dumitru Ceara <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, > 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 vs github.com. I would suspect > that people mostly go to 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 > . 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 <[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).
Regards, Han _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
