Documentation/filesystems/xfs/xfs-maintainer-entry-profile.rst

   1 XFS Maintainer Entry Profile
   2 ============================
   3
   4 Overview
   5 --------
   6 XFS is a well known high-performance filesystem in the Linux kernel.
   7 The aim of this project is to provide and maintain a robust and
   8 performant filesystem.
   9
  10 Patches are generally merged to the for-next branch of the appropriate
  11 git repository.
  12 After a testing period, the for-next branch is merged to the master
  13 branch.
  14
  15 Kernel code are merged to the xfs-linux tree[0].
  16 Userspace code are merged to the xfsprogs tree[1].
  17 Test cases are merged to the xfstests tree[2].
  18 Ondisk format documentation are merged to the xfs-documentation tree[3].
  19
  20 All patchsets involving XFS *must* be cc'd in their entirety to the mailing
  21 list linux-xfs@vger.kernel.org.
  22
  23 Roles
  24 -----
  25 There are eight key roles in the XFS project.
  26 A person can take on multiple roles, and a role can be filled by
  27 multiple people.
  28 Anyone taking on a role is advised to check in with themselves and
  29 others on a regular basis about burnout.
  30
  31 - **Outside Contributor**: Anyone who sends a patch but is not involved
  32   in the XFS project on a regular basis.
  33   These folks are usually people who work on other filesystems or
  34   elsewhere in the kernel community.
  35
  36 - **Developer**: Someone who is familiar with the XFS codebase enough to
  37   write new code, documentation, and tests.
  38
  39   Developers can often be found in the IRC channel mentioned by the ``C:``
  40   entry in the kernel MAINTAINERS file.
  41
  42 - **Senior Developer**: A developer who is very familiar with at least
  43   some part of the XFS codebase and/or other subsystems in the kernel.
  44   These people collectively decide the long term goals of the project
  45   and nudge the community in that direction.
  46   They should help prioritize development and review work for each release
  47   cycle.
  48
  49   Senior developers tend to be more active participants in the IRC channel.
  50
  51 - **Reviewer**: Someone (most likely also a developer) who reads code
  52   submissions to decide:
  53
  54   0. Is the idea behind the contribution sound?
  55   1. Does the idea fit the goals of the project?
  56   2. Is the contribution designed correctly?
  57   3. Is the contribution polished?
  58   4. Can the contribution be tested effectively?
  59
  60   Reviewers should identify themselves with an ``R:`` entry in the kernel
  61   and fstests MAINTAINERS files.
  62
  63 - **Testing Lead**: This person is responsible for setting the test
  64   coverage goals of the project, negotiating with developers to decide
  65   on new tests for new features, and making sure that developers and
  66   release managers execute on the testing.
  67
  68   The testing lead should identify themselves with an ``M:`` entry in
  69   the XFS section of the fstests MAINTAINERS file.
  70
  71 - **Bug Triager**: Someone who examines incoming bug reports in just
  72   enough detail to identify the person to whom the report should be
  73   forwarded.
  74
  75   The bug triagers should identify themselves with a ``B:`` entry in
  76   the kernel MAINTAINERS file.
  77
  78 - **Release Manager**: This person merges reviewed patchsets into an
  79   integration branch, tests the result locally, pushes the branch to a
  80   public git repository, and sends pull requests further upstream.
  81   The release manager is not expected to work on new feature patchsets.
  82   If a developer and a reviewer fail to reach a resolution on some point,
  83   the release manager must have the ability to intervene to try to drive a
  84   resolution.
  85
  86   The release manager should identify themselves with an ``M:`` entry in
  87   the kernel MAINTAINERS file.
  88
  89 - **Community Manager**: This person calls and moderates meetings of as many
  90   XFS participants as they can get when mailing list discussions prove
  91   insufficient for collective decisionmaking.
  92   They may also serve as liaison between managers of the organizations
  93   sponsoring work on any part of XFS.
  94
  95 - **LTS Maintainer**: Someone who backports and tests bug fixes from
  96   uptream to the LTS kernels.
  97   There tend to be six separate LTS trees at any given time.
  98
  99   The maintainer for a given LTS release should identify themselves with an
 100   ``M:`` entry in the MAINTAINERS file for that LTS tree.
 101   Unmaintained LTS kernels should be marked with status ``S: Orphan`` in that
 102   same file.
 103
 104 Submission Checklist Addendum
 105 -----------------------------
 106 Please follow these additional rules when submitting to XFS:
 107
 108 - Patches affecting only the filesystem itself should be based against
 109   the latest -rc or the for-next branch.
 110   These patches will be merged back to the for-next branch.
 111
 112 - Authors of patches touching other subsystems need to coordinate with
 113   the maintainers of XFS and the relevant subsystems to decide how to
 114   proceed with a merge.
 115
 116 - Any patchset changing XFS should be cc'd in its entirety to linux-xfs.
 117   Do not send partial patchsets; that makes analysis of the broader
 118   context of the changes unnecessarily difficult.
 119
 120 - Anyone making kernel changes that have corresponding changes to the
 121   userspace utilities should send the userspace changes as separate
 122   patchsets immediately after the kernel patchsets.
 123
 124 - Authors of bug fix patches are expected to use fstests[2] to perform
 125   an A/B test of the patch to determine that there are no regressions.
 126   When possible, a new regression test case should be written for
 127   fstests.
 128
 129 - Authors of new feature patchsets must ensure that fstests will have
 130   appropriate functional and input corner-case test cases for the new
 131   feature.
 132
 133 - When implementing a new feature, it is strongly suggested that the
 134   developers write a design document to answer the following questions:
 135
 136   * **What** problem is this trying to solve?
 137
 138   * **Who** will benefit from this solution, and **where** will they
 139     access it?
 140
 141   * **How** will this new feature work?  This should touch on major data
 142     structures and algorithms supporting the solution at a higher level
 143     than code comments.
 144
 145   * **What** userspace interfaces are necessary to build off of the new
 146     features?
 147
 148   * **How** will this work be tested to ensure that it solves the
 149     problems laid out in the design document without causing new
 150     problems?
 151
 152   The design document should be committed in the kernel documentation
 153   directory.
 154   It may be omitted if the feature is already well known to the
 155   community.
 156
 157 - Patchsets for the new tests should be submitted as separate patchsets
 158   immediately after the kernel and userspace code patchsets.
 159
 160 - Changes to the on-disk format of XFS must be described in the ondisk
 161   format document[3] and submitted as a patchset after the fstests
 162   patchsets.
 163
 164 - Patchsets implementing bug fixes and further code cleanups should put
 165   the bug fixes at the beginning of the series to ease backporting.
 166
 167 Key Release Cycle Dates
 168 -----------------------
 169 Bug fixes may be sent at any time, though the release manager may decide to
 170 defer a patch when the next merge window is close.
 171
 172 Code submissions targeting the next merge window should be sent between
 173 -rc1 and -rc6.
 174 This gives the community time to review the changes, to suggest other changes,
 175 and for the author to retest those changes.
 176
 177 Code submissions also requiring changes to fs/iomap and targeting the
 178 next merge window should be sent between -rc1 and -rc4.
 179 This allows the broader kernel community adequate time to test the
 180 infrastructure changes.
 181
 182 Review Cadence
 183 --------------
 184 In general, please wait at least one week before pinging for feedback.
 185 To find reviewers, either consult the MAINTAINERS file, or ask
 186 developers that have Reviewed-by tags for XFS changes to take a look and
 187 offer their opinion.
 188
 189 References
 190 ----------
 191 | [0] https://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git/
 192 | [1] https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git/
 193 | [2] https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git/
 194 | [3] https://git.kernel.org/pub/scm/fs/xfs/xfs-documentation.git/