doc: coding guidelines: Add a new rule for macro name collisions

This commit is the outcome of the discussion that has taken place in
multiple forums:

Discord:
https://discord.com/channels/720317445772017664/1014241011989487716/1032623375228608522

GitHub:
zephyrproject-rtos/zephyr#51371
zephyrproject-rtos/zephyr#50239

(cherry picked from commit d095f7d)

Original-Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
GitOrigin-RevId: d095f7d
Change-Id: I473d1b1f55da92b34bd429cd60f0cf75488ed5d4
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/zephyr/+/4287511
Tested-by: Keith Short <keithshort@chromium.org>
Reviewed-by: Keith Short <keithshort@chromium.org>
Tested-by: Al Semjonovs <asemjonovs@google.com>
Commit-Queue: Al Semjonovs <asemjonovs@google.com>
Tested-by: CopyBot Service Account <copybot.service@gmail.com>
Reviewed-by: Al Semjonovs <asemjonovs@google.com>

doc/contribute/coding_guidelines/index.rst

@@ -1255,6 +1255,48 @@ Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language
 .. _CAN in Automation Inclusive Language news post: https://www.can-cia.org/news/archive/view/?tx_news_pi1%5Bnews%5D=699&tx_news_pi1%5Bday%5D=6&tx_news_pi1%5Bmonth%5D=12&tx_news_pi1%5Byear%5D=2020&cHash=784e79eb438141179386cf7c29ed9438
 .. _CAN in Automation Inclusive Language: https://can-newsletter.org/canopen/categories/
 
+
+Rule A.3: Macro name collisions
+===============================
+
+Severity
+--------
+
+Required
+
+Description
+-----------
+
+Macros with commonly used names such as  ``MIN``, ``MAX``, ``ARRAY_SIZE``, must
+not be modified or protected to avoid name collisions with other
+implementations. In particular, they must not be prefixed to place them in a
+Zephyr-specific namespace, re-defined using ``#undef``, or conditionally
+excluded from compilation using ``#ifndef``.  Instead, if a conflict arises with
+an existing definition originating from a :ref:`module <modules>`, the module's
+code itself needs to be modified (ideally upstream, alternatively via a change
+in Zephyr's own fork).
+This rule applies to Zephyr as a project in general, regardless of the time of
+introduction of the macro or its current name in the tree. If a macro name is
+commonly used in several other well-known open source projects then the
+implementation in Zephyr should use that name. While there is a subjective and
+non-measurable component to what "commonly used" means, the ultimate goal is
+to offer users familiar macros.
+Finally, this rule applies to inter-module name collisions as well: in that case
+both modules, prior to their inclusion, should be modified to use
+module-specific versions of the macro name that collides.
+
+Rationale
+---------
+
+Zephyr is an RTOS that comes with additional functionality and dependencies in
+the form of modules. Those modules are typically independent projects that may
+use macro names that can conflict with other modules or with Zephyr itself.
+Since, in the context of this documentation, Zephyr is considered the central or
+main project, it should implement the non-namespaced versions of the
+macros. Given that Zephyr uses a fork of the corresponding upstream for each
+module, it is always possible to patch the macro implementation in each module
+to avoid collisions.
+
 Parasoft Codescan Tool
 **********************