[PATCH 0/2] Add maintainers to the admin guide

[PATCH 0/2] Add maintainers to the admin guide

[Mauro Carvalho Chehab]

That's my third attempt to add the MAINTAINERS contents to the admin-guide.

On the past approaches, was planning to keep the documentation
about what's at the MAINTAINERS file inside it, but that would
require running an external script or use some Sphinx extension.

This time, I took a much simpler approach: convert the initial
part of the MAINTAINERS file to ReST and move to a file at the
admin-guide. So, MAINTAINERS file will now contain only the
maintainer's database, and a single line pointing to its documentation.

That should hopefully be a good compromise, as we can add its
contents to a Sphinx file without causing too much hasle.


Mauro Carvalho Chehab (2):
  MAINTAINERS: convert first part to ReST markup
  MAINTAINERS: add it to the admin-guide

 Documentation/admin-guide/index.rst       |   1 +
 Documentation/admin-guide/maintainers.rst | 184 ++++++++++++++++++++++++++++++
 MAINTAINERS                               | 125 +-------------------
 3 files changed, 187 insertions(+), 123 deletions(-)
 create mode 100644 Documentation/admin-guide/maintainers.rst

-- 
2.9.3

[PATCH 1/2] MAINTAINERS: convert first part to ReST markup

[Mauro Carvalho Chehab]

- Fix document section markups;
- Use tables;
- Use monotonic font for field names;
- adjust spaces and blank lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 MAINTAINERS | 213 ++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 136 insertions(+), 77 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index e13497c79fe4..1cb31237a2c0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1,12 +1,14 @@
-
-
-	List of maintainers and how to submit kernel changes
+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.
 
-1.	Always _test_ your changes, however small, on at least 4 or
+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
@@ -15,7 +17,7 @@ trivial patch so apply some common sense.
 	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.)
+	SMC ``etherpower`` for that.)
 
 3.	Make sure your changes compile correctly in multiple
 	configurations. In particular check that changes work both as a
@@ -25,7 +27,7 @@ trivial patch so apply some common sense.
 	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
+	``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
@@ -33,28 +35,34 @@ trivial patch so apply some common sense.
 	your driver to get around a problem actually needs to become a
 	generalized kernel feature ready for next time.
 
-	PLEASE check your patch with the automated style checker
-	(scripts/checkpatch.pl) to catch trivial style violations.
-	See Documentation/process/coding-style.rst for guidance here.
+	.. attention::
 
-	PLEASE 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 Documentation/process/submitting-patches.rst for details.
+	  **PLEASE:**
 
-	PLEASE 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.
+	  - check your patch with the automated style checker
+	    (``scripts/checkpatch.pl``) to catch trivial style violations.
+	    See :ref:`Documentation/process/coding-style.rst <codingstyle>`
+	    for guidance here.
 
-	PLEASE document known bugs. If it doesn't work for everything
-	or does something very odd once a month document it.
+	  - 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/process/submitting-patches.rst <submittingpatches>`
+	    for details.
 
-	PLEASE 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
-	Documentation/process/submitting-patches.rst.
+	  - 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/process/submitting-patches.rst <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
@@ -66,64 +74,115 @@ trivial patch so apply some common sense.
 
 8.	Happy hacking.
 
-Descriptions of section entries:
-
-	P: Person (obsolete)
-	M: Mail patches to: FullName <address@domain>
-	R: Designated reviewer: FullName <address@domain>
-	   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/
-	   X:	net/ipv6/
-	   matches all files in and below net 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]
+Descriptions of section entries
+-------------------------------
+
+- ``P:`` Person (obsolete)
+
+- ``M:`` Mail patches to: FullName <address@domain>
+
+- ``R:`` Designated reviewer: FullName <address@domain>
+
+	- 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,
+  ``scripts/get_maintainer.pl`` 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 List (try to look for most precise areas first)
+-----------------------------------------------------------
 
 		-----------------------------------
 
+
 3C59X NETWORK DRIVER
 M:	Steffen Klassert <klassert@mathematik.tu-chemnitz.de>
 L:	netdev@vger.kernel.org
-- 
2.9.3

[PATCH 2/2] MAINTAINERS: add it to the admin-guide

[Mauro Carvalho Chehab]

The MAINTAINER's file has different things inside it:
	- Tips for patch submitters;
	- Descriptions for the MAINTAINER file entries;
	- the MAINTAINERS database.

As its contents is useful for someone reporting a bug or
by a newbie submitting a patch, let's add it to the documentation,
keeping just the database at the MAINTAINERS file, and a note
pointing to where the documentation was moved.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/admin-guide/index.rst       |   1 +
 Documentation/admin-guide/maintainers.rst | 184 ++++++++++++++++++++++++++++++
 MAINTAINERS                               | 182 +----------------------------
 3 files changed, 186 insertions(+), 181 deletions(-)
 create mode 100644 Documentation/admin-guide/maintainers.rst

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 2681cbd24cdd..a2a72b749861 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -28,6 +28,7 @@ problems and bugs in particular.
    bug-hunting
    bug-bisect
    tainted-kernels
+   maintainers
    ramoops
    dynamic-debug-howto
    init
diff --git a/Documentation/admin-guide/maintainers.rst b/Documentation/admin-guide/maintainers.rst
new file mode 100644
index 000000000000..68daef3df3cf
--- /dev/null
+++ b/Documentation/admin-guide/maintainers.rst
@@ -0,0 +1,184 @@
+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/process/coding-style.rst <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/process/submitting-patches.rst <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/process/submitting-patches.rst <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@kernel.org, especially if the maintainer
+	does not respond.
+
+8.	Happy hacking.
+
+Descriptions of section entries
+-------------------------------
+
+- ``P:`` Person (obsolete)
+
+- ``M:`` Mail patches to: FullName <address@domain>
+
+- ``R:`` Designated reviewer: FullName <address@domain>
+
+	- 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,
+  ``scripts/get_maintainer.pl`` 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]
+
+Maintainer's list
+-----------------
+
+.. include:: ../../MAINTAINERS
+   :literal:
diff --git a/MAINTAINERS b/MAINTAINERS
index 1cb31237a2c0..92bb78b75eb0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1,187 +1,7 @@
-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/process/coding-style.rst <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/process/submitting-patches.rst <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/process/submitting-patches.rst <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@kernel.org, especially if the maintainer
-	does not respond.
-
-8.	Happy hacking.
-
-Descriptions of section entries
--------------------------------
-
-- ``P:`` Person (obsolete)
-
-- ``M:`` Mail patches to: FullName <address@domain>
-
-- ``R:`` Designated reviewer: FullName <address@domain>
-
-	- 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,
-  ``scripts/get_maintainer.pl`` 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 List (try to look for most precise areas first)
 -----------------------------------------------------------
 
-		-----------------------------------
-
+Please read Documentation/admin-guide/maintainers.rst for instructions.
 
 3C59X NETWORK DRIVER
 M:	Steffen Klassert <klassert@mathematik.tu-chemnitz.de>
-- 
2.9.3

Re: [PATCH 0/2] Add maintainers to the admin guide

[Daniel Vetter]

On Fri, Dec 02, 2016 at 10:15:13AM -0200, Mauro Carvalho Chehab wrote:
> That's my third attempt to add the MAINTAINERS contents to the admin-guide.
> 
> On the past approaches, was planning to keep the documentation
> about what's at the MAINTAINERS file inside it, but that would
> require running an external script or use some Sphinx extension.
> 
> This time, I took a much simpler approach: convert the initial
> part of the MAINTAINERS file to ReST and move to a file at the
> admin-guide. So, MAINTAINERS file will now contain only the
> maintainer's database, and a single line pointing to its documentation.
> 
> That should hopefully be a good compromise, as we can add its
> contents to a Sphinx file without causing too much hasle.

Yeah, this seems like a rather neat approach and hopefully keeps everyone
happy. Will probably conflict since there's some in-flight patches to
document the new B: tag a bit better. Anyway:

Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>

> 
> 
> Mauro Carvalho Chehab (2):
>   MAINTAINERS: convert first part to ReST markup
>   MAINTAINERS: add it to the admin-guide
> 
>  Documentation/admin-guide/index.rst       |   1 +
>  Documentation/admin-guide/maintainers.rst | 184 ++++++++++++++++++++++++++++++
>  MAINTAINERS                               | 125 +-------------------
>  3 files changed, 187 insertions(+), 123 deletions(-)
>  create mode 100644 Documentation/admin-guide/maintainers.rst
> 
> -- 
> 2.9.3
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH 0/2] Add maintainers to the admin guide

[Jonathan Corbet]

On Fri,  2 Dec 2016 10:15:13 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> On the past approaches, was planning to keep the documentation
> about what's at the MAINTAINERS file inside it, but that would
> require running an external script or use some Sphinx extension.
> 
> This time, I took a much simpler approach: convert the initial
> part of the MAINTAINERS file to ReST and move to a file at the
> admin-guide. So, MAINTAINERS file will now contain only the
> maintainer's database, and a single line pointing to its documentation.

So sorry for the silence on this...I decided that I wanted to think about
it past the merge window, then promptly got buried by other stuff.

I like this approach better than one came before, but I do still have to
wonder about what the objective is.  The documentation of the MAINTAINERS
format is going to be of interest to people while the are ... looking at
or modifying MAINTAINERS.  So perhaps it's already in the most useful
place?  Are we really doing people a favor by telling them they have to
follow a pointer to a different file?  What is gained by doing that?

I won't dig in my heels against this forever, but I am curious to hear
what others think about why this change should (or should not) be made.

Thanks,

jon

Re: [PATCH 0/2] Add maintainers to the admin guide

[Joe Perches]

On Mon, 2016-12-12 at 11:00 -0700, Jonathan Corbet wrote:
> On Fri,  2 Dec 2016 10:15:13 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > On the past approaches, was planning to keep the documentation
> > about what's at the MAINTAINERS file inside it, but that would
> > require running an external script or use some Sphinx extension.
> > 
> > This time, I took a much simpler approach: convert the initial
> > part of the MAINTAINERS file to ReST and move to a file at the
> > admin-guide. So, MAINTAINERS file will now contain only the
> > maintainer's database, and a single line pointing to its documentation.
> 
> So sorry for the silence on this...I decided that I wanted to think about
> it past the merge window, then promptly got buried by other stuff.
> 
> I like this approach better than one came before, but I do still have to
> wonder about what the objective is.  The documentation of the MAINTAINERS
> format is going to be of interest to people while the are ... looking at
> or modifying MAINTAINERS.  So perhaps it's already in the most useful
> place?  Are we really doing people a favor by telling them they have to
> follow a pointer to a different file?  What is gained by doing that?
> 
> I won't dig in my heels against this forever, but I am curious to hear
> what others think about why this change should (or should not) be made.

As long as I don't have to update the get_maintainers script
just to satisfy some external desire to make it rst style
compatible, I don't much care.

About the change itself:

Does the boxing with the ======= blocks align properly?
It it really useful?  Is there another/better way?

Re: [PATCH 0/2] Add maintainers to the admin guide

[Mauro Carvalho Chehab]

Em Mon, 12 Dec 2016 12:56:50 -0800
Joe Perches <joe@perches.com> escreveu:

> On Mon, 2016-12-12 at 11:00 -0700, Jonathan Corbet wrote:
> > On Fri,  2 Dec 2016 10:15:13 -0200
> > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> >   
> > > On the past approaches, was planning to keep the documentation
> > > about what's at the MAINTAINERS file inside it, but that would
> > > require running an external script or use some Sphinx extension.
> > > 
> > > This time, I took a much simpler approach: convert the initial
> > > part of the MAINTAINERS file to ReST and move to a file at the
> > > admin-guide. So, MAINTAINERS file will now contain only the
> > > maintainer's database, and a single line pointing to its documentation.  
> > 
> > So sorry for the silence on this...I decided that I wanted to think about
> > it past the merge window, then promptly got buried by other stuff.

Yeah, MAINTAINERS and ABI are two things that require some thinking.

> > 
> > I like this approach better than one came before, but I do still have to
> > wonder about what the objective is.  The documentation of the MAINTAINERS
> > format is going to be of interest to people while the are ... looking at
> > or modifying MAINTAINERS.  So perhaps it's already in the most useful
> > place?  Are we really doing people a favor by telling them they have to
> > follow a pointer to a different file?  What is gained by doing that?

The MAINTAINERS file currently has 3 parts:

1) instructions for patch submitters;
2) descriptions about the database fields;
3) the maintainer's database.

IMHO, part (1) is misplaced. Also, before doing the conversion, I suspect
that the last time I read it were when I became a maintainer, more than
ten years ago :)

Along all those years, I read part (2) only on rare situations,
e. g. when I need to do something different. On such cases, I usually 
open MAINTAINERS file on two windows, one with part (2) and another one
on the editor where I'm filling the database. So, at least for my usecase,
it doesn't really matter if both are in the same file or on different ones.

With regards to part (3),  what I do myself, and what it seems that
new media drivers' submitters do is that they simply clone the media
subsystem's entry (or a previous clone of it) and then modify the "M:"
and the "F:" entry, eventually adding new "L:" entries, when other lists
should be c/c on patch submissions, like on this example:

	AIMSLAB FM RADIO RECEIVER DRIVER
	M:	Hans Verkuil <hverkuil@xs4all.nl>
	L:	linux-media@vger.kernel.org
	T:	git git://linuxtv.org/media_tree.git
	W:	https://linuxtv.org
	S:	Maintained
	F:	drivers/media/radio/radio-aimslab*

IMHO, the meaning of the most used fields are clear to anyone that reads the
database, even without reading part (2).

That's said, in the case of ABI database, the instructions about the
expected fields are on a separate file (Documentation/ABI/README).
That doesn't make any harder to write a new ABI file.

So, I don't see any issue on splitting the non-database stuff on
separate file(s).

Yet, if you prefer to keep them altogether, we could return back to
the previous approach of having a parser that would detect where the
database starts and show it in a literal way. On such case, we could
apply patch 1/2 and modify get_maintainers.pl to output MAINTAINERS
as a ReST format, adding a Sphinx extension that would allow calling
get_maintainers.pl.

> > I won't dig in my heels against this forever, but I am curious to hear
> > what others think about why this change should (or should not) be made.  
> 
> As long as I don't have to update the get_maintainers script
> just to satisfy some external desire to make it rst style
> compatible, I don't much care.
> 
> About the change itself:
> 
> Does the boxing with the ======= blocks align properly?
> It it really useful?  Is there another/better way?

Do you mean those?

  ===============================	================================
  ``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``
  ===============================	================================

This is a table. We might instead use a literal block, like:

::

  ``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``

But the result looks uglier when generating LaTeX or HTML, as it won't
unwrap the continuation lines of the field descriptions.

Another alternative would be to use ascii artwork, like:

 +------------------------------------+----------------------------------+
 | ``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``		 |
 +------------------------------------+----------------------------------+

That makes it better to read, at the expense that it takes more time to
handwrite.

Yet, once the tables are there, they can easily convert it to ascii artwork
with pandoc:

	$ pandoc -f rst -t rst Documentation/admin-guide/maintainers.rst 

If you think that it makes easier to read, I can replace the tables
there by their asciiart alter ego.

Thanks,
Mauro

Re: [PATCH 0/2] Add maintainers to the admin guide

[Joe Perches]

On Tue, 2016-12-13 at 07:38 -0200, Mauro Carvalho Chehab wrote:
> Em Mon, 12 Dec 2016 12:56:50 -0800
> Joe Perches <joe@perches.com> escreveu:
> > Does the boxing with the ======= blocks align properly?
> > It it really useful?  Is there another/better way?
> 
> Do you mean those?
> 
>   ===============================	================================
>   ``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``
>   ===============================	================================

Yes.

> This is a table. We might instead use a literal block, like:
> 
> ::
> 
>   ``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``
> 
> But the result looks uglier when generating LaTeX or HTML, as it won't
> unwrap the continuation lines of the field descriptions.
> 
> Another alternative would be to use ascii artwork, like:
> 
>  +------------------------------------+----------------------------------+
>  | ``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``		 |
>  +------------------------------------+----------------------------------+

Isn't the ascii art is going to get odd looking
output after the sphinx conversion because of the
doubled quotes being converted to bold?

I suspect the table formatting just isn't necessary
and it could be paragraphed instead.

Re: [PATCH 0/2] Add maintainers to the admin guide

[Mauro Carvalho Chehab]

Em Wed, 14 Dec 2016 08:14:44 -0800
Joe Perches <joe@perches.com> escreveu:

> On Tue, 2016-12-13 at 07:38 -0200, Mauro Carvalho Chehab wrote:
> > Em Mon, 12 Dec 2016 12:56:50 -0800
> > Joe Perches <joe@perches.com> escreveu:  
> > > Does the boxing with the ======= blocks align properly?
> > > It it really useful?  Is there another/better way?  
> > 
> > Do you mean those?
> > 
> >   ===============================	================================
> >   ``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``
> >   ===============================	================================  
> 
> Yes.
> 
> > This is a table. We might instead use a literal block, like:
> > 
> > ::
> > 
> >   ``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``
> > 
> > But the result looks uglier when generating LaTeX or HTML, as it won't
> > unwrap the continuation lines of the field descriptions.
> > 
> > Another alternative would be to use ascii artwork, like:
> > 
> >  +------------------------------------+----------------------------------+
> >  | ``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``		 |
> >  +------------------------------------+----------------------------------+  
> 
> Isn't the ascii art is going to get odd looking
> output after the sphinx conversion because of the
> doubled quotes being converted to bold?

Doubled quotes should be converted to monospaced fonts, and not to
bold. We might remove the double quotes, but the end result would
be worse, as we would need to escape the asterisks.

> I suspect the table formatting just isn't necessary
> and it could be paragraphed instead.

We could use indented paragraphs instead, like:

   * ``F:``   	``drivers/net/``
       all files in and below ``drivers/net``

   * ``F:``   	``*/net/*``
       all files in "any top level directory" ``/net``

But, IMHO, it would look worse than tables on both ASCII and on
formatted outputs.

Thanks,
Mauro