| Message ID | 20221117172532.538149-5-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | testing and doc updates (pre-PR) | expand |
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. Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
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>
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..05110909d1 --- /dev/null +++ b/docs/devel/maintainers.rst @@ -0,0 +1,106 @@ +.. _maintainers: + +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. + +Please bear in mind that even if someone is paid to support something +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 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. + +Becoming a maintainer +--------------------- + +Maintainers are volunteers who put themselves forward or have been +asked by others to keep an eye on an area of code. They have generally +demonstrated to the community, usually via contributions and code +reviews, that they have a good understanding of the subsystem. They +are also trusted to make a positive contribution to the project and +work well with the other contributors. + +The process is simple - simply send 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. + +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. + +.. [#] In recent pandemic times we have had to exercise some + flexibility here. Maintainers still need to sign their pull + requests though. 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