1.. _rfcs: 2 3Proposals and RFCs 4################## 5 6Many changes, including bug fixes and documentation improvements can be 7implemented and reviewed via the normal GitHub pull request workflow. 8 9Many changes however are "substantial" and need to go through a 10design process and produce a consensus among the project stakeholders. 11 12The "RFC" (request for comments) process is intended to provide a consistent and 13controlled path for new features to enter the project. 14 15Contributors and project stakeholders should consider using this process if 16they intend to make "substantial" changes to Zephyr or its documentation. Some 17examples that would benefit from an RFC are: 18 19- A new feature that creates new API surface area, and would require a feature 20 flag if introduced. 21- The modification of an existing stable API. 22- The removal of features that already shipped as part of Zephyr. 23- The introduction of new idiomatic usage or conventions, even if they do not 24 include code changes to Zephyr itself. 25 26The RFC process is a great opportunity to get more eyeballs on proposals coming 27from contributors before it becomes a part of Zephyr. Quite often, even 28proposals that seem "obvious" can be significantly improved once a wider group 29of interested people have a chance to weigh in. 30 31The RFC process can also be helpful to encourage discussions about a proposed 32feature as it is being designed, and incorporate important constraints into the 33design while it's easier to change, before the design has been fully 34implemented. 35 36For a Major Feature, first open an issue and outline your proposal so that it 37can be discussed. This will also allow us to better coordinate our efforts, 38prevent duplication of work, and help you to craft the change so that it is 39successfully accepted into the project. Providing the following information 40will increase the chances of your issue being dealt with quickly: 41 42 * Overview of the Proposal 43 * Motivation for or Use Case 44 * Design Details 45 * Alternatives 46 * Test Strategy 47 48Some changes or contributions do not require an RFC, the rationale and details 49of the changes should however be part of the pull-request: 50 51- Small enhancements and modifications to existing and established subsystems. 52- Rephrasing, reorganizing or refactoring 53- Addition or removal of warnings 54- Addition of new boards, SoCs or drivers to existing subsystems 55- ... 56 57The process in itself consists in creating a GitHub issue with the :ref:`RFC 58label <gh_labels>` that documents the proposal thoroughly. There is an `RFC 59template`_ included in the main Zephyr GitHub repository that serves as a 60guideline to write a new RFC. 61 62As with Pull Requests, RFCs might require discussion in the context of one of 63the `Zephyr meetings`_ in order to move it forward in cases where there is 64either disagreement or not enough voiced opinions in order to proceed. Make sure 65to either label it appropriately or include it in the corresponding GitHub 66project in order for it to be examined during the next meeting. 67 68.. _`RFC template`: https://github.com/zephyrproject-rtos/zephyr/blob/main/.github/ISSUE_TEMPLATE/003_rfc-proposal.md 69.. _`Zephyr meetings`: https://github.com/zephyrproject-rtos/zephyr/wiki/Zephyr-Committee-and-Working-Groups 70