Re: [PATCH v2 11/11] MAINTAINERS: use a URL for pin-init maintainer's profile entry

[Mauro Carvalho Chehab]

On Wed, 6 May 2026 10:38:07 +0200
Miguel Ojeda <miguel.ojeda.sandonis@xxxxxxxxx> wrote:

> On Wed, May 6, 2026 at 8:49 AM Mauro Carvalho Chehab
> <mchehab+huawei@xxxxxxxxxx> wrote:
> >
> > Maybe it is just me, but placing doc files in the crowd together with code
> > on a project where documentation has its own directory sounds weird(*).
> >
> > (*) except for userspace tools and staging drivers where we want
> >     everything, including documentation, contained on a single place.  
> 
> It is a similar case -- they are vendored libraries developed and used
> elsewhere (e.g. in userspace too).

I see.

> > As you're already using some scripting to do a bidirectional sync,
> > you could add there some logic to convert rust pin-init documentation
> > to rst and place it at Documentation/rust/.  
> 
> Most of the pin-init documentation is elsewhere (embedded in the Rust
> source code) and already rendered at rust.docs.kernel.org.
> 
> (Using Sphinx for Rust has been discussed in the list a few times in
> the past too, and that has its own set of constraints).
> 
> > Btw, on a quick check, only Rust has markdown files:
> >
> >         $ git ls-files|grep ".md$"|grep -v tools/
> >         rust/pin-init/CONTRIBUTING.md
> >         rust/pin-init/README.md
> >         rust/proc-macro2/README.md
> >         rust/quote/README.md
> >         rust/syn/README.md
> >
> > As one of the people who spent years helping improving the Kernel
> > documentation and doing lots of conversions from markdown
> > and other non-structured text formats to RST, I have to say that I'm
> > concerned with any trends that would add doc files that aren't
> > properly integrated with the Kernel documentation system like those.  
> 
> All those are vendored libraries, and most of those `README.md` files
> are about clarifying where they are taken from and their licensing,
> e.g.
> 
>     # `quote`
> 
>     These source files come from the Rust `quote` crate, version 1.0.40
>     (released 2025-03-12), hosted in the <https://github.com/dtolnay/quote>
>     repository, licensed under "Apache-2.0 OR MIT" and only modified to add
>     the SPDX license identifiers.
> 
>     For copyright details, please see:
> 
>         https://github.com/dtolnay/quote/blob/1.0.40/README.md#license
>         https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-APACHE
>         https://github.com/dtolnay/quote/blob/1.0.40/LICENSE-MIT

Just my two cents, but all license files that are applies to the Kernel
are already under LICENSES/ directory, and there is a document defining
how SPDX and LICENSES should be used:

	Documentation/process/license-rules.rst.

IMO it would make more sense to point to the corresponding LICENSES/ files.

> 
> i.e. they are not intended to be kernel documentation, and moving them
> away from the source files doesn't sound like an improvement,
> especially since we were explicitly requested to make the provenance
> very clear.

In this case, this sounds OK.

> We could perhaps have a list of vendored libraries in
> Documentation/rust/vendored-libraries.rst` -- that could perhaps be
> useful for some folks.

Makes sense to me.

> In any case, I understand your desire to keep things integrated in the
> kernel documentation, and I appreciate that (I also like to have
> everything neatly integrated), but please do not assume we have been
> randomly adding Markdown for no reason or that we are not trying to
> keep things properly integrated... :(

I didn't intend to imply that tose aren't properly integrated. It is
just that it raised my eyebrows seeing more doc-like files over there.

---

With regards to patch 11/11, I'll send a new version just changing
the "P" tag without dropping the .md file.

Thanks,
Mauro