On 12/10/2022 13:11, Alex Bennée wrote:

We don't currently have a clear place in the documentation to describe
the rolls and responsibilities of a maintainer. Lets create one so we
can. I've moved a few small bits out of other files to try and keep
everything in one place.

Signed-off-by: Alex Bennée <alex.ben...@linaro.org>
---
  docs/devel/code-of-conduct.rst           |  2 +
  docs/devel/index-process.rst             |  1 +
  docs/devel/maintainers.rst               | 84 ++++++++++++++++++++++++
  docs/devel/submitting-a-pull-request.rst | 12 ++--
  4 files changed, 91 insertions(+), 8 deletions(-)
  create mode 100644 docs/devel/maintainers.rst

diff --git a/docs/devel/code-of-conduct.rst b/docs/devel/code-of-conduct.rst
index 195444d1b4..f734ed0317 100644
--- a/docs/devel/code-of-conduct.rst
+++ b/docs/devel/code-of-conduct.rst
@@ -1,3 +1,5 @@
+.. _code_of_conduct:
+
  Code of Conduct
  ===============
diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst
index d0d7a200fd..d50dd74c3e 100644
--- a/docs/devel/index-process.rst
+++ b/docs/devel/index-process.rst
@@ -8,6 +8,7 @@ Notes about how to interact with the community and how and 
where to submit patch
code-of-conduct
     conflict-resolution
+   maintainers
     style
     submitting-a-patch
     trivial-patches
diff --git a/docs/devel/maintainers.rst b/docs/devel/maintainers.rst
new file mode 100644
index 0000000000..e3c7003bfa
--- /dev/null
+++ b/docs/devel/maintainers.rst
@@ -0,0 +1,84 @@
+.. _maintainers:
+
+The Roll of Maintainers
+=======================
+
+Maintainers are a critical part of the projects contributor ecosystem.
+They come from a wide range of backgrounds from unpaid hobbyists
+working in their spare time to employees who work on the project as
+part of their job. Maintainer activities include:
+
+  - reviewing patches and suggesting changes
+  - preparing pull requests for their subsystems
+  - participating other project activities

missing word: participating in other project activities

+They are also human and subject to the same pressures as everyone else
+including overload and burn out. Like everyone else they are subject
+to projects :ref:`code_of_conduct`.
+
+The MAINTAINERS file
+--------------------
+
+The `MAINTAINERS
+<https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS>`__
+file contains the canonical list of who is a maintainer. The file
+is machine readable so an appropriately configured git (see
+:ref:`cc_the_relevant_maintainer`) can automatically Cc them on
+patches that touch their area of code.
+
+The file also describes the status of the area of code to give an idea
+of how actively that section is maintained.
+
+.. list-table:: Meaning of support status in MAINTAINERS
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Status
+     - Meaning
+   * - 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.
+   * - Orphan
+     - No current maintainer.
+   * - Obsolete
+     - Old obsolete code, should use something else.
+
+Please bare in mind that even if someone is paid to support something

s/bare/bear/

+it does not mean they are paid to support you. This is open source and
+the code comes with no warranty and the project makes no guarantees
+about dealing with bugs or features requests.
+
+Becoming a maintainer
+---------------------
+
+Maintainers are volunteers who put themselves forward to keep an eye
+on an area of code. They are generally accepted by the community to
+have a good understanding of the subsystem and able to make a positive
+contribution to the project.

Is it worth making this a bit stronger such as "having a demonstrable track record of providing accepted upstream patches"? I'm not sure if this is being a bit too nit-picky, however someone could have good understanding of a subsystem such as PCI but be still unfamiliar with the QEMU's PCI APIs and how they should be used.

+The process is simple - simply sent a patch to the list that updates
+the ``MAINTAINERS`` file. Sometimes this is done as part of a larger
+series when a new sub-system is being added to the code base. This can
+also be done by a retiring maintainer who nominates their replacement
+after discussion with other contributors.

Should we also request that a patch adding to MAINTAINERS needs an R-B tag from an existing maintainer?

+Once the patch is reviewed and merged the only other step is to make
+sure your GPG key is signed.
+
+.. _maintainer_keys:
+
+Maintainer GPG Keys
+~~~~~~~~~~~~~~~~~~~
+
+GPG is used to sign pull requests so they can be identified as really
+coming from the maintainer. If your key is not already signed by
+members of the QEMU community, you should make arrangements to attend
+a `KeySigningParty <https://wiki.qemu.org/KeySigningParty>`__ (for
+example at KVM Forum) or make alternative arrangements to have your
+key signed by an attendee. Key signing requires meeting another
+community member **in person** so please make appropriate
+arrangements.
diff --git a/docs/devel/submitting-a-pull-request.rst 
b/docs/devel/submitting-a-pull-request.rst
index c9d1e8afd9..a4cd7ebbb6 100644
--- a/docs/devel/submitting-a-pull-request.rst
+++ b/docs/devel/submitting-a-pull-request.rst
@@ -53,14 +53,10 @@ series) and that "make check" passes before sending out the 
pull
  request. As a submaintainer you're one of QEMU's lines of defense
  against bad code, so double check the details.
-**All pull requests must be signed**. If your key is not already signed
-by members of the QEMU community, you should make arrangements to attend
-a `KeySigningParty <https://wiki.qemu.org/KeySigningParty>`__ (for
-example at KVM Forum) or make alternative arrangements to have your key
-signed by an attendee.  Key signing requires meeting another community
-member \*in person\* so please make appropriate arrangements.  By
-"signed" here we mean that the pullreq email should quote a tag which is
-a GPG-signed tag (as created with 'gpg tag -s ...').
+**All pull requests must be signed**. By "signed" here we mean that
+the pullreq email should quote a tag which is a GPG-signed tag (as
+created with 'gpg tag -s ...'). See :ref:`maintainer_keys` for
+details.
**Pull requests not for master should say "not for master" and have
  "PULL SUBSYSTEM whatever" in the subject tag**. If your pull request is


ATB,

Mark.

Reply via email to