michaelh/zephyr
1
0
Fork 0
Code Releases Activity

docs: Move RFCs into a separate document

Browse source 
The RFC proposal documentation better belongs with the other
documentation related to contributing to the Zephyr project.

Signed-off-by: Keith Short <keithshort@google.com>
This commit is contained in:
Keith Short 2023-02-27 18:03:28 -07:00 • committed by Carles Cufí
commit 942e4a38d2
3 changed files with 56 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

1
doc/contribute/index.rst
View file

@ -8,6 +8,7 @@ Contributing to Zephyr
guidelines.rst guidelines.rst
contributor_expectations.rst contributor_expectations.rst
proposals_and_rfcs.rst
coding_guidelines/index.rst coding_guidelines/index.rst
documentation/index.rst documentation/index.rst
external.rst external.rst

55
doc/contribute/proposals_and_rfcs.rst Normal file
View file

@ -0,0 +1,55 @@
.. _rfcs:
Proposals and RFCs
##################
Many changes, including bug fixes and documentation improvements can be
implemented and reviewed via the normal GitHub pull request workflow.
Many changes however are "substantial" and need to go through a
design process and produce a consensus among the project stakeholders.
The "RFC" (request for comments) process is intended to provide a consistent and
controlled path for new features to enter the project.
Contributors and project stakeholders should consider using this process if
they intend to make "substantial" changes to Zephyr or its documentation. Some
examples that would benefit from an RFC are:
- A new feature that creates new API surface area, and would require a feature
flag if introduced.
- The modification of an existing stable API.
- The removal of features that already shipped as part of Zephyr.
- The introduction of new idiomatic usage or conventions, even if they do not
include code changes to Zephyr itself.
The RFC process is a great opportunity to get more eyeballs on proposals coming
from contributors before it becomes a part of Zephyr. Quite often, even
proposals that seem "obvious" can be significantly improved once a wider group
of interested people have a chance to weigh in.
The RFC process can also be helpful to encourage discussions about a proposed
feature as it is being designed, and incorporate important constraints into the
design while it's easier to change, before the design has been fully
implemented.
Some changes do not require an RFC:
- Rephrasing, reorganizing or refactoring
- Addition or removal of warnings
- Addition of new boards, SoCs or drivers to existing subsystems
- ...
The process in itself consists in creating a GitHub issue with the :ref:`RFC
label <gh_labels>` that documents the proposal thoroughly. There is an `RFC
template`_ included in the main Zephyr GitHub repository that serves as a
guideline to write a new RFC.
As with Pull Requests, RFCs might require discussion in the context of one of
the `Zephyr meetings`_ in order to move it forward in cases where there is
either disagreement or not enough voiced opinions in order to proceed. Make sure
to either label it appropriately or include it in the corresponding GitHub
project in order for it to be examined during the next meeting.
.. _`RFC template`: https://github.com/zephyrproject-rtos/zephyr/blob/main/.github/ISSUE_TEMPLATE/rfc-proposal.md
.. _`Zephyr meetings`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings

56
doc/project/proposals.rst
View file

@ -60,59 +60,6 @@ by any project member or the community. You should contact an assigned owner if
you'd like to discuss or contribute to that feature's implementation you'd like to discuss or contribute to that feature's implementation
.. _rfcs:
Proposals and RFCs
*******************
Many changes, including bug fixes and documentation improvements can be
implemented and reviewed via the normal GitHub pull request workflow.
Many changes however are "substantial" and need to go through a
design process and produce a consensus among the project stakeholders.
The "RFC" (request for comments) process is intended to provide a consistent and
controlled path for new features to enter the project.
Contributors and project stakeholders should consider using this process if
they intend to make "substantial" changes to Zephyr or its documentation. Some
examples that would benefit from an RFC are:
- A new feature that creates new API surface area, and would require a feature
flag if introduced.
- The modification of an existing stable API
- The removal of features that already shipped as part of Zephyr.
- The introduction of new idiomatic usage or conventions, even if they do not
include code changes to Zephyr itself.
The RFC process is a great opportunity to get more eyeballs on proposals coming
from contributors before it becomes a part of Zephyr. Quite often, even
proposals that seem "obvious" can be significantly improved once a wider group
of interested people have a chance to weigh in.
The RFC process can also be helpful to encourage discussions about a proposed
feature as it is being designed, and incorporate important constraints into the
design while it's easier to change, before the design has been fully
implemented.
Some changes do not require an RFC:
- Rephrasing, reorganizing or refactoring
- Addition or removal of warnings
- Addition of new boards, SoCs or drivers to existing subsystems
- ...
The process in itself consists in creating a GitHub issue with the :ref:`RFC
label <gh_labels>` that documents the proposal thoroughly. There is an `RFC
template`_ included in the main Zephyr GitHub repository that serves as a
guideline to write a new RFC.
As with Pull Requests, RFCs might require discussion in the context of one of
the `Zephyr meetings`_ in order to move it forward in cases where there is
either disagreement or not enough voiced opinions in order to proceed. Make sure
to either label it appropriately or include it in the corresponding GitHub
project in order for it to be examined during the next meeting.
Roadmap and Release Plans Roadmap and Release Plans
************************* *************************
@ -157,6 +104,3 @@ and main stakeholders of the project can make progress on.
Items labeled as ``features`` are short or long term release items that shall Items labeled as ``features`` are short or long term release items that shall
have an assignee and a milestone set. have an assignee and a milestone set.
.. _`RFC template`: https://github.com/zephyrproject-rtos/zephyr/blob/main/.github/ISSUE_TEMPLATE/rfc-proposal.md
.. _`Zephyr meetings`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Group-Meetings