| Message ID | 20221012121152.1179051-2-alex.bennee@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | docs/devel suggestions for discussion | expand |
On Wed, Oct 12, 2022 at 01:11:49PM +0100, 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 s/roll/role/ in the commit description and the patch. > 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> > --- > 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. project's > +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 > + > +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`. to the project's (Although "project's" can be dropped without changing the meaning.) > + > +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 > +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. > + > +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. > + > +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 practice there are maintainers who have not yet been able to perform key signing in person. It is still possible to become a maintainer without a signed GPG key but the goal should be to get it signed as soon as practically possible. In this case the maintainer still signs pull requests with their GPG key but the commit logs will show that the key is not trusted and extra scrutiny is applied when merging code. > 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 > -- > 2.34.1 >
Alex Bennée <alex.bennee@linaro.org> writes: > 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.bennee@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 Do you mean "Role"? > +======================= > + > +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 participating in I think this doesn't quite do justice to what we expect maintainers to do. Besides shepherding patches, we expect maintainers to guard the integrity of their subsystem and the "health" of the developer community. We generally defer to a maintainer's reasoned judgement. This means a maintainer has a certain power to say no. With power comes responsibility. > + > +They are also human and subject to the same pressures as everyone else > +including overload and burn out. Like everyone else they are subject burnout > +to projects :ref:`code_of_conduct`. Arguably even more so than "ordinary" contributors, because by their visibility they necessarily serve as role models. With power comes responsibility. Should we add something on how a maintainer could get advice? Say when they have to deal with bad behavior. > + > +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 bear in mind > +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. "Volunteers who put themselves forward"... The press gangs wielding clubs are a figment of your drunken imagination! > 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. > + > +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. > + > +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
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.bennee@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.
Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk> writes: > On 12/10/2022 13:11, Alex Bennée wrote: [...] >> +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 Do you mean "expected by the community"? >> +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. I think existing practice varies. For something that is widely used, we generally require enough of a track record (contributions *and* reviews) to inspire confidence. But if you submit something new, say a machine, we may ask you to stick around and maintain it as a prerequisite for merging. [...]
Markus Armbruster <armbru@redhat.com> writes: > Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk> writes: > >> On 12/10/2022 13:11, Alex Bennée wrote: > > [...] > >>> +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 > > Do you mean "expected by the community"? Well I was trying to make clear how the "community" decides who should be a maintainer. We don't leave it to who's currently holding the merge keys so in practice its other contributors acknowledging that the proposed maintainer knows their stuff (or at least didn't step backwards fast enough when the call went out). In practice when maintainership is passed down this is often just the R-b by the previous maintainer. For areas where no maintainer currently exists just gathering a few R-b's seems to be enough because having a maintainer is better than not having one. > >>> +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. > > I think existing practice varies. > > For something that is widely used, we generally require enough of a > track record (contributions *and* reviews) to inspire confidence. I can certainly add language about prior contributions. > But if you submit something new, say a machine, we may ask you to stick > around and maintain it as a prerequisite for merging. > > [...]
On Fri, 14 Oct 2022 at 14:31, Alex Bennée <alex.bennee@linaro.org> wrote: > > > Markus Armbruster <armbru@redhat.com> writes: > > > Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk> writes: > > > >> On 12/10/2022 13:11, Alex Bennée wrote: > > > > [...] > > > >>> +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 > > > > Do you mean "expected by the community"? > > Well I was trying to make clear how the "community" decides who should > be a maintainer. We don't leave it to who's currently holding the merge > keys so in practice its other contributors acknowledging that the > proposed maintainer knows their stuff (or at least didn't step backwards > fast enough when the call went out). I think there are also two parts or stages to this: (1) is there somebody who's agreed to review patches, look at incoming bugs, etc for a particular bit of the code and is probably the 'local expert' on it? (2) who is accumulating these patches and eventually sending a pull request? For a lot of the smaller sub-areas of QEMU (e.g. specific board types or specific devices) these might be two different people. And we might trust somebody to be able to do code review and patch triage but prefer the patches to flow through the tree of some other maintainer who's more experienced with sending pull requests. -- PMM
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 + +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 +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. + +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. + +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
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.bennee@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