Re: [PATCH v3 04/13] docs/devel: add a maintainers section to development process

[Alex Bennée]

Philippe Mathieu-Daudé <philmd@linaro.org> writes:

> 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.bennee@linaro.org>
>> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
>> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
>> Message-Id: <20221111145529.4020801-6-alex.bennee@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 <rhacker@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.

I've used a slightly different form for the flow:

  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 <rhacker@example.com>

  marks you as a 'designated reviewer' - expected to provide regular
  spontaneous feedback. This will ensure that patches touching a given
  subsystem will automatically be CC'd to you.

we can of course always improve later ;-)

>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>


-- 
Alex Bennée