HOMEPAGE and SRC_URI format

Signed-off-by: Michał Górny <mgorny@gentoo.org>

1 files changed, 39 insertions, 0 deletions

diff --git a/ebuild-format.rst b/ebuild-format.rst
index 9f78705..d2c8dc5 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -48,3 +48,42 @@ converted into eclasses.
 the principle of least surprise.  It makes the maintenance harder,
 confuses other developers and tools that do not explicitly account for
 that possibility, including linting tools.
+
+
+.. index:: homepage; variable
+
+HOMEPAGE must not contain variables
+-----------------------------------
+:Source: QA
+:Reported: by pkgcheck, highlighted as error by gentoo-syntax
+
+The ``HOMEPAGE`` variable in ebuild must specify all the URIs verbatim,
+without referring to any variables.  Variable references are allowed
+when setting generic values in eclasses.
+
+*Rationale*: since homepage URIs do not contain dynamic parts (such
+as package versions), there is little advantage to using variables
+there.  On the other hand, variables render the URIs unusable without
+preprocessing, breaking URI support in terminals and editors, as well
+as reducing the usefulness of plain tools such as grep.
+
+
+
+.. index::
+   pair: src uri; homepage
+
+SRC_URI must not refer to HOMEPAGE
+----------------------------------
+:Source: QA
+:Reported: by pkgcheck
+
+The ``SRC_URI`` variable in ebuild must not refer to ``${HOMEPAGE}``.
+If both overlap, the common part must be repeated verbatim.
+
+*Rationale*: ``HOMEPAGE`` permits multiple entries by design,
+and developers are generally encouraged to add more helpful entries
+(e.g. project pages on PyPI, GitHub...).  Making individual URIs
+incidentally depend on multi-valued variable having a single value
+goes against the principle of least surprise.  Furthermore, it makes
+it hard to copy-paste part of the URI e.g. to investigate the directory
+index.