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

[Michał Górny]

commit:     7becf8322c2e53b484faa5565df3c3fcde2be85d
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 13:53:05 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 20:10:03 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=7becf832

dependencies: =-deps with no revision

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

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

diff --git a/dependencies.rst b/dependencies.rst
index ff6756f..51038be 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -30,6 +30,34 @@ This is especially important for packages that take long time to build.
    by the Council but no reference implementation has been written.
 
 
+.. index:: dependency; = with no revision
+
+=-dependencies with no revision
+-------------------------------
+:Source: QA
+:Reported: by repoman and pkgcheck
+
+Whenever a non-wildcard ``=`` (equals) dependency is used on a package,
+the requested revision must be specified explicitly.  When the zeroth
+revision is requested, ``-r0`` must be used.  When no specific revision
+is necessary, the ``~`` (tilde) operator must be used instead.
+
+*Example*::
+
+    # BAD:
+    =dev-libs/libfrobnicate-1.2.3
+    # GOOD:
+    =dev-libs/libfrobnicate-1.2.3-r0
+    =dev-libs/libfrobnicate-1.2.3-r3
+    ~dev-libs/libfrobnicate-1.2.3
+
+*Rationale*: using ``=`` operator in place of ``~`` to mean a specific
+version has been a common mistake.  This policy uses the fact that
+no revision and explicit ``-r0`` are equivalent.  By explicitly
+requesting the latter, it warns developers to reconsider whether they
+used the correct operator.
+
+
 .. index::
    pair: slot/subslot; dependency