From e041b2f5da7e6efd0e9978414a69fdd37c995026 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Tue, 11 Oct 2022 06:22:32 +0200 Subject: [PATCH] doc: treewide change requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This pull request documents additional requirements for treewide changes which were discussed at the process WG (see issue #48886 for details). These requirements apply to especially impactful changes. They exist both to try to make sure the changes get enough review, and to give users a heads-up mechanism about incoming treewide changes. Signed-off-by: Martí Bolívar --- doc/contribute/guidelines.rst | 69 +++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/doc/contribute/guidelines.rst b/doc/contribute/guidelines.rst index 3ee9135c7b..3b1b0129aa 100644 --- a/doc/contribute/guidelines.rst +++ b/doc/contribute/guidelines.rst @@ -807,3 +807,72 @@ Contributions to External Modules Follow the guidelines in the :ref:`modules` section for contributing :ref:`new modules ` and submitting changes to :ref:`existing modules `. + +.. _treewide-changes: + +Treewide Changes +**************** + +This section describes contributions that are treewide changes and some +additional associated requirements that apply to them. These requirements exist +to try to give such changes increased review and user visibility due to their +large impact. + +Definition and Decision Making +============================== + +A *treewide change* is defined as any change to Zephyr APIs, coding practices, +or other development requirements that either implies required changes +throughout the zephyr source code repository or can reasonably be expected to +do so for a wide class of external Zephyr-based source code. + +This definition is informal by necessity. This is because the decision on +whether any particular change is treewide can be subjective and may depend on +additional context. + +Project maintainers should use good judgement and prioritize the Zephyr +developer experience when deciding when a proposed change is treewide. +Protracted disagreements can be resolved by the Zephyr Project's Technical +Steering Committee (TSC), but please avoid premature escalation to the TSC. + +Requirements for Treewide Changes +================================= + +- The zephyr repository must apply the 'treewide' GitHub label to any issues or + pull requests that are treewide changes + +- The person proposing a treewide change must create an `RFC issue + `_ + describing the change, its rationale and impact, etc. before any pull + requests related to the change can be merged + +- The project's `Architecture Working Group (WG) + `_ + must include the issue on the agenda and discuss whether the project will + accept or reject the change before any pull requests related to the change + can be merged (with escalation to the TSC if consensus is not reached at the + WG) + +- The Architecture WG must specify the procedure for merging any PRs associated + with each individual treewide change, including any required approvals for + pull requests affecting specific subsystems or extra review time requirements + +- The person proposing a treewide change must email + devel@lists.zephyrproject.org about the RFC if it is accepted by the + Architecture WG before any pull requests related to the change can be merged + +Examples +======== + +Some example past treewide changes are: + +- the deprecation of version 1 of the :ref:`Logging API ` in favor + of version 2 (see commit `262cc55609 + `_) +- the removal of support for a legacy :ref:`dt-bindings` syntax + (`6bf761fc0a + `_) + +Note that adding a new version of a widely used API while maintaining +support for the old one is not a treewide change. Deprecation and removal of +such APIs, however, are treewide changes.