doc: treewide change requirements

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 <marti.bolivar@nordicsemi.no>

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 <submitting_new_modules>` and
 submitting changes to :ref:`existing modules <changes_to_existing_module>`.
+
+.. _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
+  <https://github.com/zephyrproject-rtos/zephyr/issues/new?assignees=&labels=RFC&template=rfc-proposal.md&title=>`_
+  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)
+  <https://github.com/zephyrproject-rtos/zephyr/wiki/Architecture-Working-Group>`_
+  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 <logging_api>` in favor
+  of version 2 (see commit `262cc55609
+  <https://github.com/zephyrproject-rtos/zephyr/commit/262cc55609b73ea61b5f999c6c6daaba20bc5240>`_)
+- the removal of support for a legacy :ref:`dt-bindings` syntax
+  (`6bf761fc0a
+  <https://github.com/zephyrproject-rtos/zephyr/commit/6bf761fc0a2811b037abec0c963d60b00c452acb>`_)
+
+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.