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