[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     0719b0f628b12a542b4e9b3327ab493c0e1daf76
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 20:29:58 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Jan 21 16:47:48 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=0719b0f6

dependencies: policy on 4-style USE deps

Closes: https://bugs.gentoo.org/705890
Closes: https://github.com/gentoo/policy-guide/pull/8
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 dependencies.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/dependencies.rst b/dependencies.rst
index 38f4147..55bba5c 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -167,5 +167,46 @@ dependencies as a result.
    if the package installed by the user still links to libfoo.
 
 
+.. index::
+   pair: USE flags; dependency
+
+USE dependencies
+----------------
+
+on packages without the flag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:Source: QA (inferred from PMS)
+:Reported: by pkgcheck
+
+Whenever a package uses a 2-style USE-dependency on another package,
+all package versions matching the dependency must have the flag
+in question.  If the dependency matches at least one version missing
+the flag, either 4-style USE-dependency (i.e. having ``(-)`` or ``(+)``
+indicator) must be used, or the restriction must be refined to match
+only versions having the flag.
+
+*Example*::
+
+    # BAD: USE=gtk2 is not supported by v2
+    dev-foo/libfrobnicate[gtk2]
+    # GOOD: all matching versions have USE=tools
+    <dev-foo/libfrobnicate-2[gtk2]
+    # GOOD: indicate the default
+    dev-foo/libfrobnicate[gtk2(-)]
+
+    # BAD: USE=tools is no longer needed with v2
+    dev-foo/libbar[tools]
+    # GOOD: indicate the default
+    dev-foo/libbar[tools(+)]
+
+*Rationale*: according to the PMS section on `2-style and 4-style USE
+dependencies`_, it is an error to apply 2-style USE dependency to
+a package missing the flag.  Furthermore, checking for this makes it
+possible to report whenever USE flags on a package are changed without
+updating its reverse dependencies.
+
+
 .. _GLEP 62: https://www.gentoo.org/glep/glep-0062.html
 .. _Paludis: https://paludis.exherbo.org/
+.. _2-style and 4-style USE dependencies:
+     https://projects.gentoo.org/pms/7/pms.html#x1-790008.2.6.4