Document the community RFC process (#116386)
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.
This commit is contained in:
Aaron Ballman
GitHub
parent
ac56d6ea28
commit
4424a587be
@ -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
|
||||
====================
|
||||
|
||||
@ -596,11 +596,6 @@ having this ability would help that work.
|
||||
Proposing Major Changes (RFCs)
|
||||
------------------------------
|
||||
|
||||
LLVM is a large community with many stakeholders, and before landing any major
|
||||
change, it is important to discuss the design of a change publicly with the
|
||||
community. This is done by posting a Request For Comments (RFC) on the `LLVM
|
||||
Discourse forums`_.
|
||||
|
||||
The design of LLVM is carefully controlled to ensure that all the pieces fit
|
||||
together well and are as consistent as possible. If you plan to make a major
|
||||
change to the way LLVM works or want to add a major new extension, it is a good
|
||||
@ -609,45 +604,13 @@ significant effort in an implementation. Prototype implementations, however, can
|
||||
often be helpful in making design discussions more concrete by demonstrating
|
||||
what is possible.
|
||||
|
||||
These are some suggestions for how to get a major change accepted:
|
||||
LLVM is a large community with many stakeholders, and before landing any major
|
||||
change, it is important to discuss the design of a change publicly with the
|
||||
community. This is done by posting a Request For Comments (RFC) on the `LLVM
|
||||
Discourse forums`_. See the :doc:`RFC process <RFCProcess>` documentation for
|
||||
more details.
|
||||
|
||||
* Make it targeted, and avoid touching components irrelevant to the task.
|
||||
|
||||
* Explain how the change improves LLVM for other stakeholders rather than
|
||||
focusing on your specific use case.
|
||||
|
||||
* As discussion evolves, periodically summarize the current state of the
|
||||
discussion and clearly separate points where consensus seems to emerge from
|
||||
those where further discussion is necessary.
|
||||
|
||||
* Compilers are foundational infrastructure, so there is a high quality bar,
|
||||
and the burden of proof is on the proposer. If reviewers repeatedly ask for
|
||||
an unreasonable amount of evidence or data, proposal authors can escalate to
|
||||
the area team to resolve disagreements.
|
||||
|
||||
After posting a major proposal, it is common to receive lots of conflicting
|
||||
feedback from different parties, or no feedback at all, leaving authors without
|
||||
clear next steps. As a community, we are aiming for `"rough consensus"
|
||||
<https://en.wikipedia.org/wiki/Rough_consensus>`_, similar in spirit to what is
|
||||
described in `IETF RFC7282 <https://datatracker.ietf.org/doc/html/rfc7282>`_.
|
||||
This requires considering and addressing all of the objections to the RFC, and
|
||||
confirming that we can all live with the tradeoffs embodied in the proposal.
|
||||
|
||||
The LLVM Area Teams (defined in `LP0004
|
||||
<https://github.com/llvm/llvm-www/blob/main/proposals/LP0004-project-governance.md>`_)
|
||||
are responsible for facilitating project decision making. In cases where there
|
||||
isn't obvious agreement, area teams should step in to restate their perceived
|
||||
consensus. In cases of deeper disagreement, area teams should try to identify
|
||||
the next steps for the proposal, such as gathering more data, changing the
|
||||
proposal, or rejecting it outright. They can also act as moderators by
|
||||
scheduling calls for participants to speak directly to resolve disagreements,
|
||||
subject to normal :ref:`Code of Conduct <LLVM Community Code of Conduct>`
|
||||
guidelines.
|
||||
|
||||
Once the design of the new feature is finalized, the work itself should be done
|
||||
as a series of `incremental changes`_, not as a long-term development branch.
|
||||
|
||||
.. _incremental changes:
|
||||
.. _incremental-changes:
|
||||
|
||||
Incremental Development
|
||||
-----------------------
|
||||
@ -877,6 +840,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
|
||||
@ -1065,7 +1029,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
|
||||
@ -1116,7 +1081,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
|
||||
@ -1160,7 +1126,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
|
||||
|
||||
@ -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:
|
||||
|
||||
125
llvm/docs/RFCProcess.rst
Normal file
125
llvm/docs/RFCProcess.rst
Normal file
@ -0,0 +1,125 @@
|
||||
=================================
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
After posting a major proposal, it is common to receive lots of conflicting
|
||||
feedback from different parties, or no feedback at all, leaving authors without
|
||||
clear next steps. As a community, we are aiming for `"rough consensus"
|
||||
<https://en.wikipedia.org/wiki/Rough_consensus>`_, similar in spirit to what is
|
||||
described in `IETF RFC7282 <https://datatracker.ietf.org/doc/html/rfc7282>`_.
|
||||
This requires considering and addressing all of the objections to the RFC, and
|
||||
confirming that we can all live with the tradeoffs embodied in the proposal.
|
||||
|
||||
The LLVM Area Teams (defined in `LP0004
|
||||
<https://github.com/llvm/llvm-www/blob/main/proposals/LP0004-project-governance.md>`_)
|
||||
are responsible for facilitating project decision making. In cases where there
|
||||
isn't obvious agreement, area teams should step in to restate their perceived
|
||||
consensus. In cases of deeper disagreement, area teams should try to identify
|
||||
the next steps for the proposal, such as gathering more data, changing the
|
||||
proposal, or rejecting it in the absence of major changes in the design or
|
||||
context. They can also act as moderators by scheduling calls for participants
|
||||
to speak directly to resolve disagreements, subject to normal
|
||||
:ref:`Code of Conduct <LLVM Community Code of Conduct>` guidelines.
|
||||
|
||||
Once the design of the new feature is finalized, the work itself should be done
|
||||
as a series of :ref:`incremental changes <incremental-changes>`, not as a long-term development branch.
|
||||
|
||||
|
||||
Trivial Acceptance or Rejection
|
||||
-------------------------------
|
||||
Some proposals have obvious consensus (for or against) after discussion in the
|
||||
community. It is acceptable to presume a post which appears to have obvious
|
||||
consensus has been accepted.
|
||||
|
||||
Non-trivial Acceptance or Rejection
|
||||
-----------------------------------
|
||||
If the proposal does not have obvious consensus after community discussion,
|
||||
a maintainer for each of the impacted parts of the project should explicitly
|
||||
accept or reject the RFC by leaving a comment stating their decision and
|
||||
possibly detailing any 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
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
If the 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, the appropriate area team 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. 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
|
||||
---------------
|
||||
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.
|
||||
|
||||
Suggestions on Getting a Change Accepted
|
||||
----------------------------------------
|
||||
These are some suggestions for how to get a major change accepted:
|
||||
|
||||
* Make it targeted, and avoid touching components irrelevant to the task.
|
||||
|
||||
* Explain how the change improves LLVM for other stakeholders rather than
|
||||
focusing on your specific use case.
|
||||
|
||||
* As discussion evolves, periodically summarize the current state of the
|
||||
discussion and clearly separate points where consensus seems to emerge from
|
||||
those where further discussion is necessary.
|
||||
|
||||
* Compilers are foundational infrastructure, so there is a high quality bar,
|
||||
and the burden of proof is on the proposer. If reviewers repeatedly ask for
|
||||
an unreasonable amount of evidence or data, proposal authors can escalate to
|
||||
the area team to resolve disagreements.
|
||||
@ -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`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user