On 17/11/22 18:25, Alex Bennée wrote:
We don't currently have a clear place in the documentation to describe
the roles 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>
Reviewed-by: Stefan Hajnoczi <stefa...@redhat.com>
Reviewed-by: Paolo Bonzini <pbonz...@redhat.com>
Message-Id: <20221111145529.4020801-6-alex.ben...@linaro.org>
---
docs/devel/code-of-conduct.rst | 2 +
docs/devel/index-process.rst | 1 +
docs/devel/maintainers.rst | 106 +++++++++++++++++++++++
docs/devel/submitting-a-pull-request.rst | 12 +--
4 files changed, 113 insertions(+), 8 deletions(-)
create mode 100644 docs/devel/maintainers.rst
+The Role of Maintainers
+=======================
+
+Maintainers are a critical part of the project's 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
+ - collecting patches and preparing pull requests
+ - tending to the long term health of their area
+ - participating in other project activities
+
+They are also human and subject to the same pressures as everyone else
+including overload and burnout. Like everyone else they are subject
+to project's :ref:`code_of_conduct` and should also be exemplars of
+excellent community collaborators.
+
+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.
We could add a line in MAINTAINERS 'Descriptions of section entries'
header: "If you modify this section, please keep in sync with the
description in docs/devel/maintainers.rst".
+Becoming a reviewer
+-------------------
+
+Most maintainers start by becoming subsystem reviewers. While anyone
+is welcome to review code on the mailing list getting added to the
+MAINTAINERS file with a line like::
+
+ R: Random Hacker <rhac...@example.com>
+
+will ensure that patches touching a given subsystem will automatically
+be CC'd to you.
Although 'R:' tag means 'designated reviewer', such reviewers is
expected to provide regular spontaneous feedback. Otherwise being
subscribed to the list is sufficient.
Reviewed-by: Philippe Mathieu-Daudé <phi...@linaro.org>
