Message-ID: <20160923120733.546a4b7a@vento.lan>
Date:   Fri, 23 Sep 2016 12:07:33 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: [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 <my@...e>
L: mailing@...t
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 <my@...e>
  L: mailing@...t
  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 <mchehab@...pensource.com>
---

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 000000000000..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.	Make a patch available to the relevant maintainer in the list. Use
+	``diff -u`` to make the patch easy to merge. Be prepared to get your
+	changes sent back with seemingly silly requests about formatting
+	and variable names.  These aren't as silly as they seem. One
+	job the maintainers (and especially Linus) do is to keep things
+	looking the same. Sometimes this means that the clever hack in
+	your driver to get around a problem actually needs to become a
+	generalized kernel feature ready for next time.
+
+	.. attention::
+
+	  **PLEASE:**
+
+	  - check your patch with the automated style checker
+	    (``scripts/checkpatch.pl``) to catch trivial style violations.
+	    See :ref:`Documentation/CodingStyle <codingstyle>` for guidance
+	    here.
+
+	  - CC: the maintainers and mailing lists that are generated
+	    by ``scripts/get_maintainer.pl``.  The results returned by the
+	    script will be best if you have git installed and are making
+	    your changes in a branch derived from Linus' latest git tree.
+	    See :ref:`Documentation/SubmittingPatches <submittingpatches>`
+	    for details.
+
+	  - try to include any credit lines you want added with the
+	    patch. It avoids people being missed off by mistake and makes
+	    it easier to know who wants adding and who doesn't.
+
+	  - document known bugs. If it doesn't work for everything
+	    or does something very odd once a month document it.
+
+	  - remember that submissions must be made under the terms
+	    of the Linux Foundation certificate of contribution and should
+	    include a Signed-off-by: line.  The current version of this
+	    "Developer's Certificate of Origin" (DCO) is listed in the file
+	    :ref:`Documentation/SubmittingPatches <submittingpatches>`.
+
+6.	Make sure you have the right to send any changes you make. If you
+	do changes at work you may find your employer owns the patch
+	not you.
+
+7.	When sending security related changes or reports to a maintainer
+	please Cc: security@...nel.org, especially if the maintainer
+	does not respond.
+
+8.	Happy hacking.
+
+Descriptions of section entries
+-------------------------------
+
+-	``P:`` Person (obsolete)
+-	``M:`` Mail patches to: FullName <address@...ain>
+-	``R:`` Designated reviewer: FullName <address@...ain>
+
+	- These reviewers should be CCed on patches.
+
+-	``L:`` Mailing list that is relevant to this area
+-	``W:`` Web-page with status/info
+-	``Q:`` Patchwork web based patch tracking system site
+-	``T:`` SCM tree type and location.
+
+	- Type is one of: **git**, **hg**, **quilt**, **stgit**, **topgit**
+
+-	``S:`` Status, one of the following:
+
+	   - Supported:
+			Someone is actually paid to look after this.
+	   - Maintained:
+			Someone actually looks after it.
+	   - Odd Fixes:
+			It has a maintainer but they don't have time to do
+			much other than throw the odd patch in. See below..
+	   - Orphan:
+			No current maintainer [but maybe you could take the
+			role as you write your new code].
+	   - Obsolete:
+			Old code. Something tagged obsolete generally means
+			it has been replaced by a better system and you
+			should be using that.
+-	``F:`` Files and directories with wildcard patterns.
+
+	   A trailing slash includes all files and subdirectory files.
+
+	   ============================== ======================================
+	   ``F:``	``drivers/net/``	all files in and below
+						``drivers/net``
+	   ``F:``	``drivers/net/*``	all files in ``drivers/net``,
+						but not below
+	   ``F:``	``*/net/*``		all files in "any top level
+						directory" ``/net``
+	   ============================== ======================================
+
+	   One pattern per line.  Multiple ``F:`` lines acceptable.
+-	``N:`` Files and directories with regex patterns.
+
+	   ============================ ========================================
+	   ``N:``	``[^a-z]tegra``		all files whose path contains
+						the word ``tegra``
+	   ============================ ========================================
+
+	   One pattern per line.  Multiple ``N:`` lines acceptable.
+	   ``scripts/get_maintainer.pl`` has different behavior for files that
+	   match ``F:`` pattern and matches of ``N:`` patterns.  By default,
+	   get_maintainer will not look at git log history when an ``F:``
+	   pattern match occurs.  When an ``N:`` match occurs, git log history
+	   is used to also notify the people that have git commit signatures.
+-	``X:`` Files and directories that are NOT maintained, same rules as
+	``F:`` Files exclusions are tested before file matches.
+	Can be useful for excluding a specific subdirectory, for instance:
+
+	   ============================ ========================================
+	   ``F:``	``net/``	matches all files in and below
+					``net`` ...
+	   ``X:``	``net/ipv6/``	... excluding ``net/ipv6/``
+	   ============================ ========================================
+
+-	``K:`` Keyword perl extended regex pattern to match content in a
+	   patch or file.  For instance:
+
+	   =========================================== =========================
+	   ``K:`` ``of_get_profile``			matches patches or files
+							that contain
+							``of_get_profile``
+	   ``K:`` ``\b(printk|pr_(info|err))\b``	matches patches or
+							files that contain one
+							or more of the words
+							``printk``, ``pr_info``
+							or ``pr_err``
+	   =========================================== =========================
+
+	   One regex pattern per line.  Multiple ``K:`` lines acceptable.
+
+.. note::
+
+  For the hard of thinking, this list is meant to remain in alphabetical
+  order. If you could add yourselves to it in alphabetical order that would be
+  so much easier [Ed]
+
+Maintainers
+-----------
+
+.. program-output:: awk '/----------/{y=1;next}y' ../../MAINTAINERS
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 6762af7fc7f5..5c31fb0dc90f 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -21,3 +21,4 @@ Contents:
    binfmt_misc
    bad_memory
    basic_profiling
+   MAINTAINERS
diff --git a/MAINTAINERS b/MAINTAINERS
index 46a2ce64df68..17fc1b5dacb5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2,6 +2,9 @@
 
 	List of maintainers and how to submit kernel changes
 
+NOTE: if you update the instuctions below, you should also update
+Documentation/user/MAINTAINERS.rst.
+
 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.
-- 
2.7.4

Powered by blists - more mailing lists