michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: contrib guidelines: modify rule about adding links

Browse source 
Clarify linking issues in PRs and Commit messages and address the issue
of ambiguity across multiple github repos.

Not allowing links in commit messages so that forks can be happy is not
great.

Forks on Github have no problem with linking, however,
disconnected forks seem to not link correctly, but then why does this
matter?

If someone is taking Zephyr and developing it as their own, they
can for sure do that, but why this should force the Zephyr project to
manage traceability differently and make it more difficult for
developers to add such information in the git metadata directly and not
relying on pull requests.

Most developers use git directly and rely less on pull request and
github UI when browsing changes in the code base.. We need to be able to
see by looking at git commits and git
history if a commit is associated with a bug, some PRs might fix
multiple issues, so the context is important and by looking at each
commit the trace can be established immesiately without going back to
github pull requests.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2025-05-14 05:40:11 -04:00 • committed by Benjamin Cabé
commit bb5a929c62
1 changed files with 21 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

32
doc/contribute/guidelines.rst
View file

@ -481,31 +481,41 @@ in the Git commit's ``Author:`` field.
See the :ref:`contributor-expectations` for a more complete discussion of See the :ref:`contributor-expectations` for a more complete discussion of
contributor and reviewer expectations. contributor and reviewer expectations.
Adding links Adding Links
------------ ------------
.. _GitHub references: .. _GitHub references:
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
Do not include `GitHub references`_ in the commit message directly, as it can If your change addresses a specific GitHub issue, include a reference in the
lose meaning in case the repository is forked, for example. Instead, if the pull request description using the following format:
change addresses a specific GitHub issue, include in the Pull Request message a
line of the form: .. code-block:: none
Fixes zephyrproject-rtos/zephyr#[issue number]
For pull requests to the Zephyr project only, the short form can also be used,
for example:
.. code-block:: none .. code-block:: none
Fixes #[issue number] Fixes #[issue number]
Where ``[issue number]`` is the relevant GitHub issue's number. For Replace [issue number] with the relevant GitHub issue number. For example:
example:
.. code-block:: none .. code-block:: none
Fixes: #1234 Fixes zephyrproject-rtos/zephyr#1234
You can point to other relevant information that can be found on the web using This syntax ensures that the issue is automatically closed when the pull
:code:`Link:` tags. This includes, for example: GitHub issues, datasheets, request is merged. Always specify the full repository path
reference manuals, etc. (zephyrproject-rtos/zephyr) to avoid ambiguity, especially when working across
multiple repositories.
The same format can also be used in commit messages.
For linking to additional external resources—such as related issues,
datasheets, or technical reference manuals—use the ``Link:`` tag:
.. code-block:: none .. code-block:: none