Re: [PATCH net-next 9/9] net: document RFC6724 rule 5.5 implementation

[David 'equinox' Lamparter <equinox@diac24.net>]

On Tue, Jul 14, 2026 at 07:01:13AM -0600, Jonathan Corbet wrote:
> David 'equinox' Lamparter <equinox@diac24.net> writes:
> >  create mode 100644 Documentation/networking/ipv6-addrsel.rst
>
> You need to add this new document to the index.rst file or it won't be
> part of the docs build...you should have seen a warning when you built
> the docs.

Indeed... I missed it between the other warnings.  Downside of doing
clean runs without a sphinx cache, sigh.

> > +====================================
> > +IPv6 source address selection trivia
> > +====================================
> > +
> > +
> > +RFC6724 rule 5.5 support
> > +------------------------
>
> Please stick with the section markup guidelines in
> Documentation/doc-guide/sphinx.rst.

Oh, you mean I shouldn't skip the "Chapter" level?

Now that you mention it, maybe I should include the file from ipv6.rst,
and remove the document title entirely - it looks quite weird in the TOC
with the direct reference from index.rst.  (Or rather, I've made weird
choices with the headings.)  Does that sound good to you?

(Or, I could just put the entire text into ipv6.rst...)

> > +RFC6724 rule 5.5 is a very short paragraph in a complex RFC that has turned
> > +out quite tricky, but also immensely useful in multihoming scenarios.  For
> > +reference, it says:
> > +
> > +::
> 
> You'll likely get more visually pleasing results if you just leave out
> the "::" here; you don't need literal formatting.

I did that because RFCs are historically shipped & cited monospaced, and
that's direct from the RFC.  My tendency is to keep it this way for
"established convention" reasons, but I don't care that much - does
anyone have stronger feelings?

> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index f3218abefd0c..4edf48362a07 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -18912,6 +18912,7 @@ F:	Documentation/netlink/specs/rt-addr.yaml
> >  F:	Documentation/netlink/specs/rt-neigh.yaml
> >  F:	Documentation/netlink/specs/rt-route.yaml
> >  F:	Documentation/netlink/specs/rt-rule.yaml
> > +F:	Documentation/networking/ipv6-addrsel.rst
> 
> It seems weird to add this one file here - I wonder why there isn't just
> an entry for Documentation/networking ?

There is, the difference is "NETWORKING [GENERAL]" vs "NETWORKING
[IPv4/IPv6]".  I wasn't sure how much this matters & decided to err on
the side of caution (and also because checkpatch complained.)  I'll go
drop the line.

Thanks,


-equi