diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst index b40ca051f23e741..b81ec24724c0804 100644 --- a/doc/contribute/index.rst +++ b/doc/contribute/index.rst @@ -8,6 +8,7 @@ Contributing to Zephyr guidelines.rst committer_expectations.rst + proposals_and_rfcs.rst coding_guidelines/index.rst documentation/index.rst external.rst diff --git a/doc/contribute/proposals_and_rfcs.rst b/doc/contribute/proposals_and_rfcs.rst new file mode 100644 index 000000000000000..0d90e02e2058aca --- /dev/null +++ b/doc/contribute/proposals_and_rfcs.rst @@ -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 ` 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 diff --git a/doc/project/proposals.rst b/doc/project/proposals.rst index f331bfdcbfb5cb7..ab93ab29ac04be9 100644 --- a/doc/project/proposals.rst +++ b/doc/project/proposals.rst @@ -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 -.. _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 ` 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 ************************* @@ -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 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