[llvm] Document the community RFC process (PR #116386)
Aaron Ballman via llvm-commits
llvm-commits at lists.llvm.org
Tue Nov 19 06:51:13 PST 2024
https://github.com/AaronBallman updated https://github.com/llvm/llvm-project/pull/116386
>From e7aa3b7c64fc10234874cdf12c2da2be388bc5b9 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Fri, 15 Nov 2024 09:26:22 -0500
Subject: [PATCH 1/2] Document the community RFC process
This adds documentation about how the community RFC process works,
based on how the community typically runs RFCs. The goal is to roughly
document the process as-is and then post a follow-up explaining how the
new governance model ties in to the RFC process. From there, we can
discuss any changes to the process we would like to make via... an RFC.
---
llvm/docs/CodeReview.rst | 3 +-
llvm/docs/DeveloperPolicy.rst | 10 +++--
llvm/docs/Lexicon.rst | 3 +-
llvm/docs/RFCProcess.rst | 80 +++++++++++++++++++++++++++++++++++
llvm/docs/index.rst | 2 +
5 files changed, 93 insertions(+), 5 deletions(-)
create mode 100644 llvm/docs/RFCProcess.rst
diff --git a/llvm/docs/CodeReview.rst b/llvm/docs/CodeReview.rst
index 4cfd91435247cd..2218a66c2f1c77 100644
--- a/llvm/docs/CodeReview.rst
+++ b/llvm/docs/CodeReview.rst
@@ -93,7 +93,8 @@ intrinsics), adding language extensions in Clang, and so on, require an RFC
first. For changes that promise significant impact on users and/or downstream
code bases, reviewers can request an RFC achieving consensus before proceeding
with code review. That having been said, posting initial patches can help with
-discussions on an RFC.
+discussions on an RFC. See the :doc:`RFC process <RFCProcess>` documentation
+for more details.
Code-Review Workflow
====================
diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst
index c50e100443cf35..e6c80b3c1cce23 100644
--- a/llvm/docs/DeveloperPolicy.rst
+++ b/llvm/docs/DeveloperPolicy.rst
@@ -791,6 +791,7 @@ will only be done through the following process:
library features LLVM should use; avoid miscompiles in particular compiler
versions, etc).
- Detail downsides on important platforms (e.g. Ubuntu LTS status).
+ - See the :doc:`RFC process <RFCProcess>` documentation for more details.
* Once the RFC reaches consensus, update the CMake toolchain version checks as
well as the :doc:`getting started<GettingStarted>` guide. This provides a
@@ -979,7 +980,8 @@ Those wishing to add a new target to LLVM must follow the procedure below:
your target and how it follows all the requirements and what work has been
done and will need to be done to accommodate the official target requirements.
Make sure to expose any and all controversial issues, changes needed in the
- base code, table gen, etc.
+ base code, table gen, etc. See the :doc:`RFC process <RFCProcess>`
+ documentation for more details.
3. Once the response is positive, the LLVM community can start reviewing the
actual patches (but they can be prepared before, to support the RFC). Create
a sequence of N patches, numbered '1/N' to 'N/N' (make sure N is an actual
@@ -1030,7 +1032,8 @@ components to a high bar similar to "official targets", they:
clear path to resolving them.
* Must be proposed through the LLVM RFC process, and have its addition approved
by the LLVM community - this ultimately mediates the resolution of the
- "should" concerns above.
+ "should" concerns above. See the :doc:`RFC process <RFCProcess>`
+ documentation for more details.
If you have a project that you think would make sense to add to the LLVM
monorepo, please start an RFC topic on the `LLVM Discourse forums`_ to kick off
@@ -1074,7 +1077,8 @@ criteria:
suggested wording below).
* Must be proposed through the LLVM RFC process, and have its addition
approved by the LLVM community - this ultimately mediates the resolution of
- the "should" concerns above.
+ the "should" concerns above. See the :doc:`RFC process <RFCProcess>`
+ documentation for more details.
That said, the project need not have any code to get started, and need not have
an established community at all! Furthermore, incubating projects may pass
diff --git a/llvm/docs/Lexicon.rst b/llvm/docs/Lexicon.rst
index 1d4894f78ca883..c06379af840f61 100644
--- a/llvm/docs/Lexicon.rst
+++ b/llvm/docs/Lexicon.rst
@@ -261,7 +261,8 @@ R
**RFC**
Request for Comment. An email sent to a project mailing list in order to
- solicit feedback on a proposed change.
+ solicit feedback on a proposed change. See also: the :doc:`RFC process <RFCProcess>`
+ documentation.
.. _roots:
.. _stack roots:
diff --git a/llvm/docs/RFCProcess.rst b/llvm/docs/RFCProcess.rst
new file mode 100644
index 00000000000000..504d9da17ef080
--- /dev/null
+++ b/llvm/docs/RFCProcess.rst
@@ -0,0 +1,80 @@
+=================================
+Request For Comment (RFC) process
+=================================
+
+.. contents::
+ :local:
+ :depth: 1
+
+Introduction
+============
+Substantive changes to LLVM projects need to be acceptable to the wider
+community, which requires gaining community consensus to adopt the changes.
+This is done by posting an RFC and obtaining feedback about the proposal.
+
+Process
+=======
+
+Writing an RFC
+--------------
+The process begins with writing a proposal for the changes you'd like to see
+made. The proposal should include:
+
+* a high-level overview of what changes are being proposed,
+* information detailing the motivation for why the changes are being proposed,
+* detailed information the proposed changes and how they impact different parts
+ of the project, and
+* a list of any open questions the community should explicitly address.
+
+Once the contents of the proposal are ready, the proposal should be posted to
+the appropriate forum on `Discourse <https://discourse.llvm.org/>`_.
+
+Feedback Period
+---------------
+Once the RFC is posted, the community will provide feedback on the proposal.
+The feedback period is a collaborative effort between the community and the
+proposal authors. Authors should take the community's feedback into
+consideration and edit the original post to incorporate relevant changes they
+agree to. Edits should be made such that it's clear what has changed. Editing
+the original post makes it easier for the community to understand the proposal
+without having to read every comment on the thread, though this can make
+reading the comment thread somewhat more difficult as comments may be referring
+to words no longer in the proposal.
+
+There is not a set time limit to the feedback period; it lasts as long as
+discussion is actively continuing on the proposal.
+
+Trivial Acceptance or Rejection
+-------------------------------
+If the proposal has obvious consensus (for or against), a maintainer for each
+of the impacted parts of the project will explicitly accept or reject the RFC
+by leaving a comment stating their decision and possibly detailing any
+provisions for their acceptance. Additionally, the original post should be
+edited to explicitly say what consensus was called and link to the comment
+stating that decision. Including that information in the post makes it more
+clear to everyone what state the proposal is in. Overall consensus is
+determined once all impacted parts of the project have accepted the proposal.
+
+Low Engagement Level
+~~~~~~~~~~~~~~~~~~~~
+If a proposal gets little or no engagement by the community, it is a sign that
+the proposal does not have consensus and is rejected. Engagement means comments
+on the proposal. If there are few or no comments but the are a lot of people
+pressing the like/heart button on the post, maintainers can make a value
+judgement on whether to accept or reject.
+
+After Acceptance
+----------------
+Once an RFC has been accepted, the authors may begin merging pull requests
+related to the proposal. The review process may identify necessary changes to
+the proposal. Minor changes to the proposal do not require an additional RFC.
+However, if the proposal changes significantly in a material way, the authors
+may be asked to run another RFC.
+
+After Rejection
+---------------
+Any rejected RFC can be brought back to the community as a new RFC in the
+future. The new RFC should either clearly identify new information that may
+change the community's perception of the proposal and/or explicitly address the
+concerns previously raised by the community. It is helpful to explicitly call
+out such information in the subsequent RFC.
diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst
index b480729aaa5d9f..3f6364fb899c34 100644
--- a/llvm/docs/index.rst
+++ b/llvm/docs/index.rst
@@ -86,9 +86,11 @@ LLVM welcomes contributions of all kinds. To learn more, see the following artic
:hidden:
GettingInvolved
+ RFCProcess
* :doc:`GettingInvolved`
* :ref:`development-process`
+* :doc:`RFCProcess`
* :ref:`lists-forums`
* :ref:`meetups-social-events`
* :ref:`community-proposals`
>From c657da7c25b8a53306589b03dcf7530a12068075 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Tue, 19 Nov 2024 09:50:46 -0500
Subject: [PATCH 2/2] Rewordings based on review feedback
---
llvm/docs/RFCProcess.rst | 29 +++++++++++++----------------
1 file changed, 13 insertions(+), 16 deletions(-)
diff --git a/llvm/docs/RFCProcess.rst b/llvm/docs/RFCProcess.rst
index 504d9da17ef080..f260d77450ea8b 100644
--- a/llvm/docs/RFCProcess.rst
+++ b/llvm/docs/RFCProcess.rst
@@ -20,14 +20,13 @@ Writing an RFC
The process begins with writing a proposal for the changes you'd like to see
made. The proposal should include:
-* a high-level overview of what changes are being proposed,
-* information detailing the motivation for why the changes are being proposed,
-* detailed information the proposed changes and how they impact different parts
- of the project, and
-* a list of any open questions the community should explicitly address.
+* a detailed overview of the proposed changes,
+* the motivation for why the changes are being proposed,
+* the impact on different parts of the project, and
+* any open questions the community should address.
-Once the contents of the proposal are ready, the proposal should be posted to
-the appropriate forum on `Discourse <https://discourse.llvm.org/>`_.
+The proposal should be posted to the appropriate forum on
+`Discourse <https://discourse.llvm.org/>`_.
Feedback Period
---------------
@@ -49,11 +48,8 @@ Trivial Acceptance or Rejection
If the proposal has obvious consensus (for or against), a maintainer for each
of the impacted parts of the project will explicitly accept or reject the RFC
by leaving a comment stating their decision and possibly detailing any
-provisions for their acceptance. Additionally, the original post should be
-edited to explicitly say what consensus was called and link to the comment
-stating that decision. Including that information in the post makes it more
-clear to everyone what state the proposal is in. Overall consensus is
-determined once all impacted parts of the project have accepted the proposal.
+provisions for their acceptance. Overall consensus is determined once a
+maintainer from each impacted part of the project has accepted the proposal.
Low Engagement Level
~~~~~~~~~~~~~~~~~~~~
@@ -66,10 +62,11 @@ judgement on whether to accept or reject.
After Acceptance
----------------
Once an RFC has been accepted, the authors may begin merging pull requests
-related to the proposal. The review process may identify necessary changes to
-the proposal. Minor changes to the proposal do not require an additional RFC.
-However, if the proposal changes significantly in a material way, the authors
-may be asked to run another RFC.
+related to the proposal. While the RFC process typically makes reviewing the
+pull requests go more smoothly, the review process may identify additional
+necessary changes to the proposal. Minor changes to the proposal do not require
+an additional RFC. However, if the proposal changes significantly in a material
+way, the authors may be asked to run another RFC.
After Rejection
---------------
More information about the llvm-commits
mailing list