[PATCH v2] NFSD: Add a subsystem policy document

[PATCH v2] NFSD: Add a subsystem policy document

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

Steer contributors to NFSD's patchworks instance, list our patch
submission preferences, and more.

The new document is based on the existing netdev and xfs subsystem
policy documents.

Suggested-by: Darrick J. Wong <djwong@kernel.org>
Cc: Luis Chamberlain <mcgrof@kernel.org>
Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
---
 .../nfs/nfsd-maintainer-entry-profile.rst     | 439 ++++++++++++++++++
 .../maintainer/maintainer-entry-profile.rst   |   1 +
 MAINTAINERS                                   |   1 +
 3 files changed, 441 insertions(+)
 create mode 100644 Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst

Changes since RFC:
* Re-structured the "Patch Preparation" section
* Added a mention of the term uber "maintainer" role
* "Key Cycle Dates" renamed "Patch Acceptance"
* Added description of the nfsd-fixes branch
* Section on sensitive patches expanded

diff --git a/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst b/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst
new file mode 100644
index 000000000000..04fd50e1f43c
--- /dev/null
+++ b/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst
@@ -0,0 +1,439 @@
+NFSD Maintainer Entry Profile
+=============================
+
+A Maintainer Entry Profile supplements the top-level process
+documents (submitting-patches, submitting drivers...) with customs
+that are specific to a subsystem and its maintainers. A contributor
+uses this document to set their expectations and avoid common
+mistakes. A maintainer may use these profiles to look across
+subsystems for opportunities to converge on best common practices.
+
+Overview
+--------
+The Network File System (NFS) is a standardized family of network
+protocols that enable access to files across a set of network-
+connected peer hosts. Applications on NFS clients access files that
+reside on file systems that are shared by NFS servers. A single
+network peer can act as both an NFS client and an NFS server.
+
+NFSD refers to the NFS server implementation included in the Linux
+kernel. An in-kernel NFS server has fast access to files stored
+in file systems local to that server. NFSD can share files stored
+on most of the file system types native to Linux, including xfs,
+ext4, btrfs, and tmpfs.
+
+Mailing list
+------------
+The linux-nfs@vger.kernel.org mailing list is a public list. Its
+purpose is to enable collaboration among developers working on the
+Linux NFS stack, both client and server. It is not a place for
+conversations that are not related directly to the Linux NFS stack.
+
+The linux-nfs mailing list is archived on lore.kernel.org.
+
+The Linux NFS community does not have a chat room.
+
+Reporting bugs
+--------------
+If you experience an NFSD-related bug on a distribution-built
+kernel, please start by working with your Linux distributor.
+
+Bug reports against upstream Linux code bases are welcome on the
+linux-nfs@vger.kernel.org mailing list, where some active triage
+can be done. NFSD bugs may also be reported in the Linux kernel
+community's bugzilla at:
+
+  https://bugzilla.kernel.org
+
+Please file NFSD-related bugs under the "Filesystems/NFSD"
+component. In general, including as much detail as possible is a
+good start.
+
+For user space software related to NFSD, such as mountd or the
+exportfs command, report problems on linux-nfs@vger.kernel.org.
+You might be asked to move the report to a specific bug tracker.
+
+Contributor's Guide
+-------------------
+
+Standards compliance
+~~~~~~~~~~~~~~~~~~~~
+The NFSD community strives to provide an NFS server implementation
+that interoperates with standards-compliant NFS client
+implementations. This is done by staying close to the normative
+mandates in IETF's NFS standards documents.
+
+It is always useful to provide an RFC and section citation in a
+code comment where behavior deviates from the standard (and even
+when the behavior is compliant but the implementation is curious).
+
+On the rare occasion when deviation from standards are needed,
+clear documentation of the use case or deficiencies in the
+standard is a required part of code documentation.
+
+Note that care must always be taken to avoid leaking local error
+codes (ie, errnos) to clients of NFSD. A proper NFS status code
+is always required.
+
+Testing
+~~~~~~~
+The kdevops project
+
+  https://github.com/linux-kdevops/kdevops
+
+contains several NFS-specific workflows, as well as the community
+standard fstests suite. These workflows are based on open source
+testing tools such as ltp and fio. Contributors are encouraged to
+use these tools without kdevops, or contributors should install and
+use kdevops themselves to verify their patches before submission.
+
+Coding style
+~~~~~~~~~~~~
+Follow the coding style preferences described in
+
+  Documentation/process/coding-style.rst
+
+with the following exceptions:
+
+- Add new local variables to a function in reverse Christmas tree
+  order
+
+- Use the kdoc comment style for
+  + non-static functions
+  + static inline functions
+  + static functions that are callbacks/virtual functions
+
+- All new function names start with "nfsd_" for non-NFS-version-
+  specific functions.
+
+- New function names that are specific to NFSv2 or NFSv3, or are
+  used by all minor versions of NFSv4, use "nfsdN_" where N is
+  the version.
+
+- New function names specific to an NFSv4 minor version can be
+  named with "nfsd4M_" where M is the minor version.
+
+Patch preparation
+~~~~~~~~~~~~~~~~~
+Read and follow all guidelines in
+
+  Documentation/process/submitting-patches.rst
+
+Use tagging to identify all patch authors. However, reviewers and
+testers should be added by replying to the email patch submission.
+Email is extensively used in order to publicly archive review and
+testing attributions. These tags are automatically inserted into
+your patches when they are applied.
+
+The code in the body of the diff already shows /what/ is being
+changed. Thus it is not necessary to repeat that in the patch
+description. Instead, the description should contain one or more
+of:
+
+- A brief problem statement ("what is this patch trying to fix?")
+  with a root-cause analysis.
+
+- End-user visible symptoms or items that a support engineer might
+  use to search for the patch, like stack traces.
+
+- A brief explanation of why the patch is the best way to address
+  the problem.
+
+- Any context that reviewers might need to understand the changes
+  made by the patch.
+
+- Any relevant benchmarking results, and/or functional test results.
+
+As detailed in Documentation/process/submitting-patches.rst,
+identify the point in history that the issue being addressed was
+introduced by using a Fixes: tag.
+
+Mention in the patch description if that point in history cannot be
+determined -- that is, no Fixes: tag can be provided. In this case,
+please make it clear to maintainers whether an LTS backport is
+needed even though there is no Fixes: tag.
+
+The NFSD maintainers prefer to add stable tagging themselves, after
+public discussion in response to the patch submission. Contributors
+may suggest stable tagging, but be aware that many version
+management tools add such stable Cc's when you post your patches.
+Don't add "Cc: stable" unless you are absolutely sure the patch
+needs to go to stable during the initial submission process.
+
+Patch submission
+~~~~~~~~~~~~~~~~
+Patches to NFSD are submitted via the kernel's email-based review
+process that is common to most other kernel subsystems.
+
+Just before each submission, rebase your patch or series on the
+nfsd-testing branch at
+
+  https://git.kernel.org/pub/scm/linux/kernel/git/cel/linux.git
+
+The NFSD subsystem is maintained separately from the Linux in-kernel
+NFS client. The NFSD maintainers do not normally take submissions
+for client changes, nor can they respond authoritatively to bug
+reports or feature requests for NFS client code.
+
+This means that contributors might be asked to resubmit patches if
+they were emailed to the incorrect set of maintainers and reviewers.
+This is not a rejection, but simply a correction of the submission
+process.
+
+When in doubt, consult the NFSD entry in the MAINTAINERS file to
+see which files and directories fall under the NFSD subsystem.
+
+The proper set of email addresses for NFSD patches are:
+
+To: the NFSD maintainers and reviewers listed in MAINTAINERS
+Cc: linux-nfs@vger.kernel.org and optionally linux-kernel@
+
+If there are other subsystems involved in the patches (for example
+MM or RDMA) their primary mailing list address can be included in
+the Cc: field. Other contributors and interested parties may be
+included there as well.
+
+In general we prefer that contributors use common patch email tools
+such as "git send-email" or "stg email format/send", which tend to
+get the details right without a lot of fuss.
+
+A series consisting of a single patch is not required to have a
+cover letter. However, a cover letter can be included if there is
+substantial context that is not appropriate to include in the
+patch description.
+
+Please note that cover letters are not part of the work that is
+committed to the kernel source code base or its commit history.
+Therefore always try to keep pertinent information in the patch
+descriptions.
+
+Design documentation is welcome, but as cover letters are not
+preserved, a perhaps better option is to include a patch that adds
+such documentation under Documentation/filesystems/nfs/.
+
+Reviewers will ask about test coverage and what use cases the
+patches are expected to address. Please be prepared to answer these
+questions.
+
+Review comments from maintainers might be politely stated, but in
+general, these are not optional to address when they are actionable.
+If necessary, the maintainers retain the right to not apply patches
+when contributors refuse to address reasonable requests.
+
+Post changes to kernel source code and user space source code as
+separate series. You can connect the two series with comments in
+your cover letters.
+
+Generally the NFSD maintainers ask for a reposts even for simple
+modifications in order to publicly archive the request and the
+resulting repost before it is pulled into the NFSD trees. This
+also enables us to rebuild a patch series quickly without missing
+changes that might have been discussed via email.
+
+Avoid frequently reposting large series with only small changes. As
+a rule of thumb, posting substantial changes more than once a week
+will result in reviewer overload.
+
+Remember, there are only a handful of subsystem maintainers and
+reviewers, but potentially many sources of contributions. The
+maintainers and reviewers, therefore, are always the less scalable
+resource. Be kind to your friendly neighborhood maintainer.
+
+Patch Acceptance
+~~~~~~~~~~~~~~~~
+There isn't a formal review process for NFSD, but we like to see
+at least two Reviewed-by: notices for patches that are more than
+simple clean-ups. Reviews are done in public on
+linux-nfs@vger.kernel.org and are archived on lore.kernel.org.
+
+Currently the NFSD patch queues are maintained in branches here:
+
+  https://git.kernel.org/pub/scm/linux/kernel/git/cel/linux.git
+
+The NFSD maintainers apply patches initially to the nfsd-testing
+branch, which is always open to new submissions. Patches can be
+applied while review is ongoing. nfsd-testing is a topic branch,
+so it can change frequently, it will be rebased, and your patch
+might get dropped if there is a problem with it.
+
+Generally a script-generated "thank you" email will indicate when
+your patch has been added to the nfsd-testing branch. You can track
+the progress of your patch using the linux-nfs patchworks instance:
+
+  https://patchworks.kernel.org/linux-nfs/
+
+While your patch is in nfsd-testing, it is exposed to a variety of
+test environments, including community zero-day bots, static
+analysis tools, and NFSD continuous integration testing. The soak
+period is three to four weeks.
+
+Each patch that survives in nfsd-testing for the soak period without
+changes is moved to the nfsd-next branch.
+
+The nfsd-next branch is automatically merged into linux-next and
+fs-next on a nightly basis.
+
+Patches that survive in nfsd-next are included in the next NFSD
+merge window pull request. These windows occur once every eight
+weeks.
+
+When the upstream merge window closes, the nfsd-next branch is
+renamed nfsd-fixes, and a new nfsd-next branch is created, based on
+the upstream -rc1 tag.
+
+Fixes that are destined for an upstream -rc release also run the
+nfsd-testing gauntlet, but are then applied to the nfsd-fixes
+branch. That branch is made available for Linus to pull after a
+short time. In order to limit the risk of introducing regressions,
+we limit such fixes to emergency situations or fixes to breakage
+that occurred during the most recent upstream merge.
+
+Please make it clear when submitting an emergency patch that
+immediate action (either application to -rc or LTS backport) is
+needed.
+
+Sensitive patch submissions and bug reports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CVEs are generated by specific members of the Linux kernel community
+and several external entities. The Linux NFS community does not emit
+or assign CVEs. CVEs are assigned after an issue and its fix are
+known.
+
+However, the NFSD maintainers sometimes receive sensitive security
+reports, and at times these are significant enough to need to be
+embargoed. In such rare cases, fixes can be developed and reviewed
+out of the public eye.
+
+Please be aware that many version management tools add the stable
+Cc's when you post your patches. This is generally a nuisance, but
+it can result in outing an embargoed security issue accidentally.
+Don't add "Cc: stable" unless you are absolutely sure the patch
+needs to go to stable@ during the initial submission process.
+
+Patches that are merged without ever appearing on any list, and
+which carry a Reported-by: or Fixes: tag are detected as suspicious
+by security-focused people. We encourage that, after any private
+review, security-sensitive patches should be posted to linux-nfs@
+for the usual public review, archiving, and test period.
+
+LLM-generated submissions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The Linux kernel community as a whole is still exploring the new
+world of LLM-generated code. The NFSD maintainers will entertain
+submission of patches that are partially or wholly generated by
+LLM-based development tools. Such submissions are held to the
+same standards as submissions created entirely by human authors:
+
+- The human contributor identifies themselves via a Signed-off-by:
+  tag. This tag counts as a DoC.
+
+- The human contributor is solely responsible for code provenance
+  and any contamination by inadvertently-included code with a
+  conflicting license, as usual.
+
+- The human contributor must be able to answer and address review
+  questions. A patch description such as "This fixed my problem
+  but I don't know why" is not acceptable.
+
+- The contribution is subjected to the same test regimen as all
+  other submissions.
+
+- An indication (via a Generated-by: tag or otherwise) that the
+  contribution is LLM-generated is not required.
+
+It is easy to address review comments and fix requests in LLM
+generated code. So easy, in fact, that it becomes tempting to repost
+refreshed code immediately. Please resist that temptation.
+
+As always, please do not repost patches frequently.
+
+Clean-up patches
+~~~~~~~~~~~~~~~~
+The NFSD maintainers discourage patches which perform simple clean-
+ups, which are not in the context of other work. For example:
+
+* Addressing ``checkpatch.pl`` warnings after merge
+* Addressing :ref:`Local variable ordering<rcs>` issues
+* Addressing long-standing whitespace damage
+
+This is because it is felt that the churn that such changes produce
+comes at a greater cost than the value of such clean-ups.
+
+Conversely, spelling and grammar fixes are encouraged.
+
+Stable and LTS support
+----------------------
+Upstream NFSD continuous integration testing runs against LTS trees
+whenever they are updated.
+
+Please indicate when a patch containing a fix needs to be considered
+for LTS kernels, either via a Fixes: tag or explicit mention.
+
+Feature requests
+----------------
+Feature requests can sometimes be nebulous. A requester might not
+understand what a "use case" or "user story" is. These are
+descriptive paradigms that developers and architects use to
+understand what is required of a design.
+
+In order to prevent contributors and maintainers from becoming
+overwhelmed, we won't be afraid of saying "no" politely. However
+we can take nebulous requests and add them to our NFSD project
+Kanban board, to be fleshed in over time into an actionable
+plan for building a new feature.
+
+There is no one way to make an official feature request, but
+discussion about the request should eventually make its way to
+the linux-nfs@vger.kernel.org mailing list for public review by
+the community.
+
+Community roles and their authority
+-----------------------------------
+The purpose of Linux subsystem communities is to provide active
+stewardship of a narrow set of source files in the Linux kernel.
+This can include managing user space tooling as well.
+
+To contextualize the structure of the Linux NFS community that
+is responsible for stewardship of the NFS server code base, we
+define the community roles here.
+
+- **Contributor** : Anyone who submits a code change, bug fix,
+  recommendation, documentation fix, and so on. A contributor can
+  submit regularly or infrequently.
+
+- **Outside Contributor** : A contributor who is not a regular actor
+  in the Linux NFS community. This can mean someone who contributes
+  to other parts of the kernel, or someone who just noticed a
+  misspelling in a comment and sent a patch.
+
+- **Reviewer** : Someone who is named in the MAINTAINERS file as a
+  reviewer is an area expert who can request changes to contributed
+  code, and expects that contributors will address the request.
+
+One or more people will take on the following roles. These people
+are referred to as "maintainers." Maintainers can also contribute
+code and reviews.
+
+- **Upstream Release Manager** : This role is responsible for
+  curating contributions into a branch, reviewing test results, and
+  then sending a pull request during merge windows. There is a
+  trust relationship between the release manager and Linus.
+
+- **Bug Triager** : Someone who is a first responder to bug reports
+  submitted to the linux-nfs mailing list or the bugzilla and helps
+  troubleshoot and identify next steps.
+
+- **Testing Lead** : The testing lead builds and runs the test
+  infrastructure for the subsystem. The testing lead can ask for
+  patches to be dropped because of ongoing high defect rates.
+
+- **LTS Maintainer** : The LTS maintainer is responsible for managing
+  the Fixes: and Cc: stable annotations on patches, and seeing that
+  patches that cannot be automatically applied to LTS kernels get
+  proper backports as necessary.
+
+- **Community Manager** : This umpire role can be asked to call balls
+  and strikes during conflicts, but is also responsible for ensuring
+  the health of the relationships within the community and for
+  facilitating discussions on long-term topics such as how to manage
+  growing technical debt.
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index cda5d691e967..f185a5c86eef 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -108,5 +108,6 @@ to do something different in the near future.
    ../process/maintainer-netdev
    ../driver-api/vfio-pci-device-specific-driver-acceptance
    ../nvme/feature-and-quirk-policy
+   ../filesystems/nfs/nfsd-maintainer-entry-profile
    ../filesystems/xfs/xfs-maintainer-entry-profile
    ../mm/damon/maintainer-profile
diff --git a/MAINTAINERS b/MAINTAINERS
index f6206963efbf..b943cf6a6573 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13319,6 +13319,7 @@ R:	Dai Ngo <Dai.Ngo@oracle.com>
 R:	Tom Talpey <tom@talpey.com>
 L:	linux-nfs@vger.kernel.org
 S:	Supported
+P:	Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst
 B:	https://bugzilla.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/cel/linux.git
 F:	Documentation/filesystems/nfs/
-- 
2.51.0