Message-Id: <b3c3b85726195c8bc5ea0a4df66209c9c06b0e9b.1480680547.git.mchehab@s-opensource.com>
Date:   Fri,  2 Dec 2016 10:15:15 -0200
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        LKML <linux-kernel@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Geert Uytterhoeven <geert+renesas@...der.be>,
        Andrew Morton <akpm@...ux-foundation.org>
Subject: [PATCH 2/2] MAINTAINERS: add it to the admin-guide

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@...pensource.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@...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,
+  ``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@...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,
-  ``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@...hematik.tu-chemnitz.de>
-- 
2.9.3

Powered by blists - more mailing lists