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
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
