Skip to content

Adding links to issues

Jump to bottom Edit New page
Nathan Chancellor edited this page Apr 7, 2022 · 2 revisions

This project has a lot of history behind it and we do all of our work upstream and in the open so that it is archived and easy to refer back to why something was done. Because of this principle, it is important to use links that have a strong chance of not going dead. This is a set of best practices for various categories of links to help allow.

Linux commits

Whenever possible, always include the full SHA in the link, which will allow people to find the commit in question in a local repo or other git website if the link goes dead.

With cgit-based repositories (such as those on kernel.org), we recommend removing the branch part of the URL (h=<NAME>&) when referring to commits because if the branch goes away, the link will error out with Invalid branch: <name>. Example: https://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux.git/commit/?h=next&id=bba496656a73fc1d1330b49c7f82843836e9feb1 should become https://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux.git/commit/?id=bba496656a73fc1d1330b49c7f82843836e9feb1, in case the next branch goes away (example error).

For repositories hosted on kernel.org under the pub/scm/linux category, there are convenient URL shorteners available to avoid the above pitfall:

Certain maintainer repositories may not be stable (i.e., force push frequently), which can result in links going dead. It is recommended to use the Linux kernel's commit format to link in cases like this so that the commit message can be searched for.

$ git show --format='%h ("%s")' --no-patch fc74e0a40e4f9fd0468e34045b0c45bba11dcbb2
fc74e0a40e4f ("Linux 5.16-rc7")

This command can be aliased to something like kf (kernel format):

$ git config --global alias.kf 'show --format="%h (\"%s\")" --no-patch'

$ git kf fc74e0a40e4f9fd0468e34045b0c45bba11dcbb2
fc74e0a40e4f ("Linux 5.16-rc7")

which would then become

[fc74e0a40e4f](https://git.kernel.org/linus/fc74e0a40e4f9fd0468e34045b0c45bba11dcbb2) ("Linux 5.16-rc7")

in Markdown and look like

fc74e0a40e4f ("Linux 5.16-rc7")

Linux mailing list posts

When referring to mailing list discussions and patches, lore.kernel.org links should be used for a few reasons:

  • This infrastructure is maintained by kernel.org, so it is expected to be stable.
  • The message ID is in the URL itself, which makes it easy to search for on other websites if this infrastructure were to ever disappear.
  • It makes it easy to fetch patches for testing with b4.

Websites such as lkml.org, marc.info, and spinics.net should be avoided whenever possible, as they are not under direct control of the kernel community and their links have no message ID in them so finding discussions if the link goes dead is nearly impossible.

Lore links follow the form of https://lore.kernel.org/<MAILING_LIST>/<MESSAGE_ID> (e.g. https://lore.kernel.org/lkml/[email protected]/) or https://lore.kernel.org/<MESSAGE_ID> (e.g. https://lore.kernel.org/[email protected]//). The latter is preferred, as it will show the full thread across all mailing lists, as sometimes a particular mailing list is only added to CC in the middle of a thread.

LLVM bug reports

LLVM bug reports used to be at Bugzilla, but they are now on GitHub. As a result, https://bugs.llvm.org/show_bug.cgi?id=<ID> links have become stale, as they might now show the current status of a bug. Unfortunately, in the Bugzilla to GitHub migration, the bug numbers did not transfer at a 1 to 1 rate so changing https://bugs.llvm.org/show_bug.cgi?id=<ID> to https://github.com/llvm/llvm-project/issues/<ID> will not work correctly. To account for this, https://llvm.org/pr<ID> should be used (e.g. https://bugs.llvm.org/show_bug.cgi?id=50440 becomes https://llvm.org/pr50440). If you must refer to a Bugzilla bug, it is recommended to use the bz shortener (e.g. https://llvm.org/bz50440).

The pr shortener works with issues that were created after the migration as well (e.g. https://llvm.org/pr52647), in case there is ever another bug migration.

LLVM commits

LLVM reviews happen on reviews.llvm.org; once they are properly reviewed, they are merged into the canonical GitHub repo. Issues should include a link to both the review as well as the commit, which should be of the form https://github.com/llvm/llvm-project/commit/<SHA>. For example:

https://reviews.llvm.org/D116128

https://github.com/llvm/llvm-project/commit/be8180af5854806a343c3dd334d97ba2c4bfadfa

The commit should always have a link to the differential review but not everyone merges their patches via arc.

Add a custom footer
Add a custom sidebar
Clone this wiki locally