docs/devel/maintainers.rst

   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.