Date:   Sun, 12 Mar 2023 22:09:38 -0500
From:   David Vernet <void@manifault.com>
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     Linux BPF <bpf@vger.kernel.org>,
        Linux Documentation <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Alexei Starovoitov <ast@kernel.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Andrii Nakryiko <andrii@kernel.org>,
        Martin KaFai Lau <martin.lau@linux.dev>,
        Song Liu <song@kernel.org>, Yonghong Song <yhs@fb.com>,
        John Fastabend <john.fastabend@gmail.com>,
        KP Singh <kpsingh@kernel.org>,
        Stanislav Fomichev <sdf@google.com>,
        Hao Luo <haoluo@google.com>, Jiri Olsa <jolsa@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        "David S. Miller" <davem@davemloft.net>,
        "Tobin C. Harding" <me@tobin.cc>
Subject: Re: [PATCH bpf-next] bpf, doc: use internal linking for link to
 netdev FAQ
Message-ID: <20230313030938.GA152792@maniforge>
References: <20230313025119.17430-1-bagasdotme@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20230313025119.17430-1-bagasdotme@gmail.com>
User-Agent: Mutt/2.2.9 (2022-11-12)
Precedence: bulk

On Mon, Mar 13, 2023 at 09:51:19AM +0700, Bagas Sanjaya wrote:
> Commit d56b0c461d19da ("bpf, docs: Fix link to netdev-FAQ target") fixes
> link to netdev FAQ documentation introduced in <blurb> introduced in
> 287f4fa99a5281 ("docs: Update references to netdev-FAQ"), although the
> former commit doesn't mention Fixes: to the latter. However, the former
> changes the link to external link to docs.kernel.org, in contrast to the
> internal linking employed by the latter.
> 
> Use :doc: directive for linking to netdev FAQ doc, while keeping the
> anchor text intact and consistency with intention of 287f4fa99a5281.
> 
> Fixes: d56b0c461d19da ("bpf, docs: Fix link to netdev-FAQ target")
> Fixes: 287f4fa99a5281 ("docs: Update references to netdev-FAQ")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

This regresses all of the warnings I fixed in d56b0c461d19da ("bpf,
docs: Fix link to netdev-FAQ target"):

[void@maniforge bpf-next]$ make -j SPHINXDIRS="bpf" htmldocs
make[2]: Nothing to be done for 'html'.
Using alabaster theme
source directory: bpf
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:125: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:150: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:207: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:232: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:398: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:414: WARNING: unknown document: '/process/maintainer-netdev'

And it also causes the netdev-FAQ links to once again be broken and not
actually point to anything.

> ---
>  Indeed, this internal linking fix should have been made against bpf
>  tree, since the problematic original linking in 287f4fa99a5281 is also
>  seen in bpf tree. If that is the case, I will rebase on that tree.
> 
>  Documentation/bpf/bpf_devel_QA.rst | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst
> index 5f5f9ccc3862b4..e523991da9e0ce 100644
> --- a/Documentation/bpf/bpf_devel_QA.rst
> +++ b/Documentation/bpf/bpf_devel_QA.rst
> @@ -128,7 +128,7 @@ into the bpf-next tree will make their way into net-next tree. net and
>  net-next are both run by David S. Miller. From there, they will go
>  into the kernel mainline tree run by Linus Torvalds. To read up on the
>  process of net and net-next being merged into the mainline tree, see
> -the `netdev-FAQ`_.
> +the :doc:`netdev-FAQ </process/maintainer-netdev>`.
>  
>  
>  
> @@ -147,7 +147,8 @@ request)::
>  Q: How do I indicate which tree (bpf vs. bpf-next) my patch should be applied to?
>  ---------------------------------------------------------------------------------
>  
> -A: The process is the very same as described in the `netdev-FAQ`_,
> +A: The process is the very same as described in the
> +:doc:`netdev-FAQ </process/maintainer-netdev>`,
>  so please read up on it. The subject line must indicate whether the
>  patch is a fix or rather "next-like" content in order to let the
>  maintainers know whether it is targeted at bpf or bpf-next.
> @@ -206,8 +207,8 @@ ii) run extensive BPF test suite and
>  Once the BPF pull request was accepted by David S. Miller, then
>  the patches end up in net or net-next tree, respectively, and
>  make their way from there further into mainline. Again, see the
> -`netdev-FAQ`_ for additional information e.g. on how often they are
> -merged to mainline.
> +:doc:`netdev-FAQ </process/maintainer-netdev>` for additional
> +information e.g. on how often they are merged to mainline.
>  
>  Q: How long do I need to wait for feedback on my BPF patches?
>  -------------------------------------------------------------
> @@ -230,7 +231,8 @@ Q: Are patches applied to bpf-next when the merge window is open?
>  -----------------------------------------------------------------
>  A: For the time when the merge window is open, bpf-next will not be
>  processed. This is roughly analogous to net-next patch processing,
> -so feel free to read up on the `netdev-FAQ`_ about further details.
> +so feel free to read up on the
> +:doc:`netdev-FAQ </process/maintainer-netdev>` about further details.
>  
>  During those two weeks of merge window, we might ask you to resend
>  your patch series once bpf-next is open again. Once Linus released
> @@ -394,7 +396,7 @@ netdev kernel mailing list in Cc and ask for the fix to be queued up:
>    netdev@vger.kernel.org
>  
>  The process in general is the same as on netdev itself, see also the
> -`netdev-FAQ`_.
> +:doc:`netdev-FAQ </process/maintainer-netdev>`.
>  
>  Q: Do you also backport to kernels not currently maintained as stable?
>  ----------------------------------------------------------------------
> @@ -410,7 +412,7 @@ Q: The BPF patch I am about to submit needs to go to stable as well
>  What should I do?
>  
>  A: The same rules apply as with netdev patch submissions in general, see
> -the `netdev-FAQ`_.
> +the :doc:`netdev-FAQ </process/maintainer-netdev>`.
>  
>  Never add "``Cc: stable@vger.kernel.org``" to the patch description, but
>  ask the BPF maintainers to queue the patches instead. This can be done
> @@ -685,7 +687,6 @@ when:
>  
>  .. Links
>  .. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/
> -.. _netdev-FAQ: https://www.kernel.org/doc/html/latest/process/maintainer-netdev.html
>  .. _selftests:
>     https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/
>  .. _Documentation/dev-tools/kselftest.rst:
> 
> base-commit: 49b5300f1f8f2b542b31d63043c2febd13edbe3a
> -- 
> An old man doll... just what I always wanted! - Clara
>