[llvm] 6773269 - Specify the developer policy around links to external resources

[Aaron Ballman via llvm-commits]

Author: Aaron Ballman
Date: 2023-08-15T07:46:40-04:00
New Revision: 677326999f270395ecaec026178fe7ed148a0068

URL: https://github.com/llvm/llvm-project/commit/677326999f270395ecaec026178fe7ed148a0068
DIFF: https://github.com/llvm/llvm-project/commit/677326999f270395ecaec026178fe7ed148a0068.diff

LOG: Specify the developer policy around links to external resources

This specifies the developer policy on adding links in source & test
files and commit messages, related to discussion at:
https://discourse.llvm.org/t/code-review-reminder-about-links-in-code-commit-messages/71847

The intent is to discourage adding links to resources that are not
available to the community as a whole (dead links, links to internal
documentation, links to internal bug trackers, etc) from source and
test files, while still allowing such links to appear in other contexts
as needed. It suggests to instead add sufficient context in the
surrounding comments to make such links unnecessary.

It also clarifies that these links can appear in commit messages as
metadata (similar to how we already have Differential Revision and
Fixes metadata with links).

Differential Revision: https://reviews.llvm.org/D155081

Added: 
    

Modified: 
    llvm/docs/DeveloperPolicy.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst
index a3012c305e4a8d..af36f7c39e63c4 100644
--- a/llvm/docs/DeveloperPolicy.rst
+++ b/llvm/docs/DeveloperPolicy.rst
@@ -201,6 +201,11 @@ features added.  Some tips for getting your testcase approved:
   entire failing program into ``llvm/test`` as this creates a *time-to-test*
   burden on all developers. Please keep them short.
 
+* Avoid adding links to resources that are not available to the entire
+  community, such as links to private bug trackers, internal corporate
+  documentation, etc. Instead, add sufficient comments to the test to provide
+  the context behind such links.
+
 Note that llvm/test and clang/test are designed for regression and small feature
 tests only. More extensive test cases (e.g., entire applications, benchmarks,
 etc) should be added to the ``llvm-test`` test suite.  The llvm-test suite is
@@ -256,6 +261,11 @@ committed to the main development branch are:
    the change (more invasive changes require more testing). A reasonable subset
    might be something like "``llvm-test/MultiSource/Benchmarks``".
 
+#. Ensure that links in source code and test files point to publicly available
+   resources and are used primarily to add additional information rather than
+   to supply critical context. The surrounding comments should be sufficient
+   to provide the context behind such links.
+
 Additionally, the committer is responsible for addressing any problems found in
 the future that the change is responsible for.  For example:
 
@@ -336,8 +346,6 @@ Below are some guidelines about the format of the message itself:
   code snippets and gory details should be left to bug comments, web
   review or the mailing list.
 
-* If the patch fixes a bug in GitHub Issues, please include the PR# in the message.
-
 * Text formatting and spelling should follow the same rules as documentation
   and in-code comments, ex. capitalization, full stop, etc.
 
@@ -346,8 +354,13 @@ Below are some guidelines about the format of the message itself:
   related commit. This could be as simple as "Revert commit NNNN because it
   caused PR#".
 
-* If the patch has been reviewed, add a link to its review page, as shown
-  `here <https://www.llvm.org/docs/Phabricator.html#committing-a-change>`_.
+* It is acceptable to add metadata to the commit message to automate processes,
+  including for downstream consumers. If the patch fixes a bug in GitHub Issues,
+  we encourage adding a reference to the issue being closed, as described
+  `here <https://llvm.org/docs/BugLifeCycle.html#resolving-closing-bugs>`_.
+  Other kinds of metadata are also acceptable, including links to resources
+  that are not available to the entire community. However, such links should
+  not be used in place of making the commit message self-explanatory.
 
 For minor violations of these recommendations, the community normally favors
 reminding the contributor of this policy over reverting. Minor corrections and