| Alex Bennée | 668725c | 2022-11-17 17:25:23 +0000 | [diff] [blame] | 1 | .. _maintainers: |
| 2 | |
| 3 | The Role of Maintainers |
| 4 | ======================= |
| 5 | |
| 6 | Maintainers are a critical part of the project's contributor ecosystem. |
| 7 | They come from a wide range of backgrounds from unpaid hobbyists |
| 8 | working in their spare time to employees who work on the project as |
| 9 | part of their job. Maintainer activities include: |
| 10 | |
| 11 | - reviewing patches and suggesting changes |
| 12 | - collecting patches and preparing pull requests |
| 13 | - tending to the long term health of their area |
| 14 | - participating in other project activities |
| 15 | |
| 16 | They are also human and subject to the same pressures as everyone else |
| 17 | including overload and burnout. Like everyone else they are subject |
| 18 | to project's :ref:`code_of_conduct` and should also be exemplars of |
| 19 | excellent community collaborators. |
| 20 | |
| 21 | The MAINTAINERS file |
| 22 | -------------------- |
| 23 | |
| 24 | The `MAINTAINERS |
| 25 | <https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS>`__ |
| 26 | file contains the canonical list of who is a maintainer. The file |
| 27 | is machine readable so an appropriately configured git (see |
| 28 | :ref:`cc_the_relevant_maintainer`) can automatically Cc them on |
| 29 | patches that touch their area of code. |
| 30 | |
| 31 | The file also describes the status of the area of code to give an idea |
| 32 | of how actively that section is maintained. |
| 33 | |
| 34 | .. list-table:: Meaning of support status in MAINTAINERS |
| 35 | :widths: 25 75 |
| 36 | :header-rows: 1 |
| 37 | |
| 38 | * - Status |
| 39 | - Meaning |
| 40 | * - Supported |
| 41 | - Someone is actually paid to look after this. |
| 42 | * - Maintained |
| 43 | - Someone actually looks after it. |
| 44 | * - Odd Fixes |
| 45 | - It has a maintainer but they don't have time to do |
| 46 | much other than throw the odd patch in. |
| 47 | * - Orphan |
| 48 | - No current maintainer. |
| 49 | * - Obsolete |
| 50 | - Old obsolete code, should use something else. |
| 51 | |
| 52 | Please bear in mind that even if someone is paid to support something |
| 53 | it does not mean they are paid to support you. This is open source and |
| 54 | the code comes with no warranty and the project makes no guarantees |
| 55 | about dealing with bugs or features requests. |
| 56 | |
| 57 | |
| 58 | |
| 59 | Becoming a reviewer |
| 60 | ------------------- |
| 61 | |
| 62 | Most maintainers start by becoming subsystem reviewers. While anyone |
| 63 | is welcome to review code on the mailing list getting added to the |
| 64 | MAINTAINERS file with a line like:: |
| 65 | |
| 66 | R: Random Hacker <rhacker@example.com> |
| 67 | |
| 68 | marks you as a 'designated reviewer' - expected to provide regular |
| 69 | spontaneous feedback. This will ensure that patches touching a given |
| 70 | subsystem will automatically be CC'd to you. |
| 71 | |
| 72 | Becoming a maintainer |
| 73 | --------------------- |
| 74 | |
| 75 | Maintainers are volunteers who put themselves forward or have been |
| 76 | asked by others to keep an eye on an area of code. They have generally |
| 77 | demonstrated to the community, usually via contributions and code |
| 78 | reviews, that they have a good understanding of the subsystem. They |
| 79 | are also trusted to make a positive contribution to the project and |
| 80 | work well with the other contributors. |
| 81 | |
| 82 | The process is simple - simply send a patch to the list that updates |
| 83 | the ``MAINTAINERS`` file. Sometimes this is done as part of a larger |
| 84 | series when a new sub-system is being added to the code base. This can |
| 85 | also be done by a retiring maintainer who nominates their replacement |
| 86 | after discussion with other contributors. |
| 87 | |
| 88 | Once the patch is reviewed and merged the only other step is to make |
| 89 | sure your GPG key is signed. |
| 90 | |
| 91 | .. _maintainer_keys: |
| 92 | |
| 93 | Maintainer GPG Keys |
| 94 | ~~~~~~~~~~~~~~~~~~~ |
| 95 | |
| 96 | GPG is used to sign pull requests so they can be identified as really |
| 97 | coming from the maintainer. If your key is not already signed by |
| 98 | members of the QEMU community, you should make arrangements to attend |
| 99 | a `KeySigningParty <https://wiki.qemu.org/KeySigningParty>`__ (for |
| 100 | example at KVM Forum) or make alternative arrangements to have your |
| 101 | key signed by an attendee. Key signing requires meeting another |
| 102 | community member **in person** [#]_ so please make appropriate |
| 103 | arrangements. |
| 104 | |
| 105 | .. [#] In recent pandemic times we have had to exercise some |
| 106 | flexibility here. Maintainers still need to sign their pull |
| 107 | requests though. |
