Philippe Mathieu-Daudé <phi...@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.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. 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 <rhac...@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é <phi...@linaro.org> -- Alex Bennée
