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
contributor and reviewer expectations.
Adding links
Adding Links
------------
.. _GitHub references:
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
lose meaning in case the repository is forked, for example. Instead, if the
change addresses a specific GitHub issue, include in the Pull Request message a
line of the form:
If your change addresses a specific GitHub issue, include a reference in the
pull request description using the following format:
.. 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
Fixes #[issue number]
Where ``[issue number]`` is the relevant GitHub issue's number. For
example:
Replace [issue number] with the relevant GitHub issue number. For example:
.. 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
:code:`Link:` tags. This includes, for example: GitHub issues, datasheets,
reference manuals, etc.
This syntax ensures that the issue is automatically closed when the pull
request is merged. Always specify the full repository path
(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