Skip to content

Commit bb5a929

Browse files
nashifkartben
authored andcommitted
doc: contrib guidelines: modify rule about adding links
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>
1 parent ea29907 commit bb5a929

File tree

1 file changed

+21
-11
lines changed

1 file changed

+21
-11
lines changed

doc/contribute/guidelines.rst

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -481,31 +481,41 @@ in the Git commit's ``Author:`` field.
481481
See the :ref:`contributor-expectations` for a more complete discussion of
482482
contributor and reviewer expectations.
483483

484-
Adding links
484+
Adding Links
485485
------------
486486

487487
.. _GitHub references:
488488
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls
489489

490-
Do not include `GitHub references`_ in the commit message directly, as it can
491-
lose meaning in case the repository is forked, for example. Instead, if the
492-
change addresses a specific GitHub issue, include in the Pull Request message a
493-
line of the form:
490+
If your change addresses a specific GitHub issue, include a reference in the
491+
pull request description using the following format:
492+
493+
.. code-block:: none
494+
495+
Fixes zephyrproject-rtos/zephyr#[issue number]
496+
497+
For pull requests to the Zephyr project only, the short form can also be used,
498+
for example:
494499

495500
.. code-block:: none
496501
497502
Fixes #[issue number]
498503
499-
Where ``[issue number]`` is the relevant GitHub issue's number. For
500-
example:
504+
Replace [issue number] with the relevant GitHub issue number. For example:
501505

502506
.. code-block:: none
503507
504-
Fixes: #1234
508+
Fixes zephyrproject-rtos/zephyr#1234
509+
510+
This syntax ensures that the issue is automatically closed when the pull
511+
request is merged. Always specify the full repository path
512+
(zephyrproject-rtos/zephyr) to avoid ambiguity, especially when working across
513+
multiple repositories.
514+
515+
The same format can also be used in commit messages.
505516

506-
You can point to other relevant information that can be found on the web using
507-
:code:`Link:` tags. This includes, for example: GitHub issues, datasheets,
508-
reference manuals, etc.
517+
For linking to additional external resources—such as related issues,
518+
datasheets, or technical reference manuals—use the ``Link:`` tag:
509519

510520
.. code-block:: none
511521

0 commit comments

Comments
 (0)