Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS
Em Fri, 23 Sep 2016 09:26:34 -0700 Joe Perches escreveu: > On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote: > > So, let's use an unusual approach: manually convert the > > text at the MAINTAINERS file head, adding it at a new > > Documentation/user/MAINTAINERS.rst, and include, as a code > > block, the rest of MAINTAINERS contents, with only the > > contents of the maintainers entries. > > > > There's a side effect of this approach: now, if the > > explanation text at the MAINTAINERS file is touched, it should be > > modified also at the Documentation/user/MAINTAINERS.rst file. > > Yet, as the number of changes there are small, this > > should be manageable. > > couldn't this be a generated file from some awk script instead > of being duplicated content with a plea to be kept in sync? Yes, using a script (awk/perl/bash/python/) is another alternative. In such case, we would need to either generate it via Makefile or to have a Sphinx extension that would tell what script to run. I actually think that a generic include-like Sphinx extension that would run a script and use its result as an included text could be interesting, as it would be a way to get rid of the Documentation/media Makefile. Thanks, Mauro
Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS
Am 23.09.2016 um 17:35 schrieb Mauro Carvalho Chehab : > Em Fri, 23 Sep 2016 09:15:01 -0600 > Jonathan Corbet escreveu: >> I'm not sure I see the value of including it in >> the docs? What am I missing here? > > It is part of the REPORTING-BUGS procedure to check MAINTAINERS and > find to what ML the bug should be reported: > > https://mchehab.fedorapeople.org/user/REPORTING-BUGS.html#how-to-report-linux-kernel-bugs > > I _suspect_ that the vast majority of Linux users don't read the > MAINTAINERS file, but, instead, just google at the net for an answer > to their troubles. > > By having it on an html file, together with other user's documentation, > the payoff is that more people should do the right thing when seeking for > bug resolutions at the right mailing lists or when reporting bugs, > ultimately helping to improve the Kernel quality. > my 2cent: and whats about a simple link into the repo? * http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/MAINTAINERS#n123 with a hint on using scripts/get_maintainer.pl ... -- Markus --
Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS
On Fri, 2016-09-23 at 12:07 -0300, Mauro Carvalho Chehab wrote: > So, let's use an unusual approach: manually convert the > text at the MAINTAINERS file head, adding it at a new > Documentation/user/MAINTAINERS.rst, and include, as a code > block, the rest of MAINTAINERS contents, with only the > contents of the maintainers entries. > > There's a side effect of this approach: now, if the > explanation text at the MAINTAINERS file is touched, it should be > modified also at the Documentation/user/MAINTAINERS.rst file. > Yet, as the number of changes there are small, this > should be manageable. couldn't this be a generated file from some awk script instead of being duplicated content with a plea to be kept in sync? > diff --git a/Documentation/user/MAINTAINERS.rst > b/Documentation/user/MAINTAINERS.rst > new file mode 100644 [etc]
Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS
Em Fri, 23 Sep 2016 09:15:01 -0600 Jonathan Corbet escreveu: > On Fri, 23 Sep 2016 12:07:33 -0300 > Mauro Carvalho Chehab wrote: > > > including MAINTAINERS using ReST is tricky, because all > > maintainer's entries are like: > > So I'm generally in favor of moving things over to RST, but I have to ask: > what's the payoff for doing that with the MAINTAINERS file? I *suppose* > it's documentation, but it's also really a flat-file database of > who-to-email information. I'm not sure I see the value of including it in > the docs? What am I missing here? It is part of the REPORTING-BUGS procedure to check MAINTAINERS and find to what ML the bug should be reported: https://mchehab.fedorapeople.org/user/REPORTING-BUGS.html#how-to-report-linux-kernel-bugs I _suspect_ that the vast majority of Linux users don't read the MAINTAINERS file, but, instead, just google at the net for an answer to their troubles. By having it on an html file, together with other user's documentation, the payoff is that more people should do the right thing when seeking for bug resolutions at the right mailing lists or when reporting bugs, ultimately helping to improve the Kernel quality. Regards, Mauro
[RFC PATCH v3] docs-rst: user: add MAINTAINERS
including MAINTAINERS using ReST is tricky, because all maintainer's entries are like: FOO SUBSYSTEM: M: My Name L: mailing@list S: Maintained F: foo/bar On ReST, this would be displayed on a single line. Using alias, like |M|, |L|, ... won't solve, as an alias in Sphinx doesn't accept breaking lines. One option would be to use code blocks for every maintainer's entry, like: FOO SUBSYSTEM:: M: My Name L: mailing@list S: Maintained F: foo/bar But this produces a complex html file, with takes a while to be parsed by Firefox. Also, it would require to rewrite the entire MAINTAINERS file, with is a terrible idea, as merging it upstream will cause lots of conflicts. So, let's use an unusual approach: manually convert the text at the MAINTAINERS file head, adding it at a new Documentation/user/MAINTAINERS.rst, and include, as a code block, the rest of MAINTAINERS contents, with only the contents of the maintainers entries. There's a side effect of this approach: now, if the explanation text at the MAINTAINERS file is touched, it should be modified also at the Documentation/user/MAINTAINERS.rst file. Yet, as the number of changes there are small, this should be manageable. Signed-off-by: Mauro Carvalho Chehab --- v2: please ignore this one: e-mail got truncated. v3: fix a typo at LKML address and on the description below. I did several tests before coming up with this patch. This one seems to be one of the best ways to handle MAINTAINERS and add it to a ReST file, without needing to change the MAINTAINERS format. IMHO, the MAINTAINERS file contains important information for patch submitters and bug reporters, so, its content would fit on either the user's manual or development-process one. If one wants to see how this will be formatted, please see: https://mchehab.fedorapeople.org/user/MAINTAINERS.html That's said, I didn't like the idea of duplicating the introductory section of MAINTAINERS into a user/MAINTAINERS.rst file. Yet, no Sphinx extension currently available would do what we need. Maybe an option would be to add an extension similar to the contrib-programoutput whose output could be either parsed as a code-block or as a ReST file. Btw, a possible improvement would be to change the script executed by programoutput, in order to replace entries like: M: Foo Bar to a more human output: Maintainer: Foo Bar Anyway, the intention of this patch is to start some discussions about how MAINTAINERS should be placed inside the Kernel documentation. Documentation/conf.py | 2 +- Documentation/user/MAINTAINERS.rst | 174 + Documentation/user/index.rst | 1 + MAINTAINERS| 3 + 4 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 Documentation/user/MAINTAINERS.rst diff --git a/Documentation/conf.py b/Documentation/conf.py index b77b23cc1a86..58e79a68033b 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,7 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain', 'sphinxcontrib.programoutput'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: diff --git a/Documentation/user/MAINTAINERS.rst b/Documentation/user/MAINTAINERS.rst new file mode 100644 index ..4e12abe83278 --- /dev/null +++ b/Documentation/user/MAINTAINERS.rst @@ -0,0 +1,174 @@ +.. NOTE: if you update the instuctions below, you should also update +.. /MAINTAINERS + +List of maintainers and how to submit kernel changes + + +Please try to follow the guidelines below. This will make things +easier on the maintainers. Not all of these guidelines matter for every +trivial patch so apply some common sense. + +Tips for patch submitters +- + +1. Always **test** your changes, however small, on at least 4 or + 5 people, preferably many more. + +2. Try to release a few ALPHA test versions to the net. Announce + them onto the kernel channel and await results. This is especially + important for device drivers, because often that's the only way + you will find things like the fact version 3 firmware needs + a magic fix you didn't know about, or some clown changed the + chips on a board and not its name. (Don't laugh! Look at the + SMC ``etherpower`` for that.) + +3. Make sure your changes compile correctly in multiple + configurations. In particular check that changes work both as a + module and built into the kernel. + +4. When you are happy with a change make it generally available for + testing and await feedback. + +5. Ma
Re: [RFC PATCH v3] docs-rst: user: add MAINTAINERS
On Fri, 23 Sep 2016 12:07:33 -0300 Mauro Carvalho Chehab wrote: > including MAINTAINERS using ReST is tricky, because all > maintainer's entries are like: So I'm generally in favor of moving things over to RST, but I have to ask: what's the payoff for doing that with the MAINTAINERS file? I *suppose* it's documentation, but it's also really a flat-file database of who-to-email information. I'm not sure I see the value of including it in the docs? What am I missing here? Thanks, jon
