[gentoo-commits] data/glep:glep-manifest commit in: /

[Michał Górny]

commit:     378f8dbc158620489965f1cf5bd6abe30a5f93c6
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Nov  5 21:11:03 2017 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Nov  5 21:11:03 2017 +0000
URL:        https://gitweb.gentoo.org/data/glep.git/commit/?id=378f8dbc

glep-0074: More suggestions from Robin H. Johnson

 glep-0074.rst | 61 ++++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 35 insertions(+), 26 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index e4d6a80..aae8fcf 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -125,9 +125,10 @@ that are not otherwise ignored, they need to be covered by an explicit
 
 All the local (non-``DIST``) files covered by a Manifest tree must
 reside on the same filesystem. It is an error to specify entries
-applying to files on another filesystem. If subdirectories
-that are not otherwise ignored reside on a different filesystem, they
-must be explicitly excluded via ``IGNORE``.
+applying to files on another filesystem. If files or directories that
+are not otherwise ignored reside on a different filesystem, or symbolic
+links point to targets on a different filesystem, they must
+be explicitly excluded via ``IGNORE``.
 
 
 File verification
@@ -194,7 +195,7 @@ The Manifest files can specify the following tags:
   to detect an outdated repository checkout as described in `Timestamp
   verification`_.
 
-``MANIFEST <path> <size> <checksums>…``
+``MANIFEST <path> <size> <checksums>...``
   Specifies a sub-Manifest. The sub-Manifest must be verified like
   a regular file. If the verification succeeds, the entries from
   the sub-Manifest are included for verification as described
@@ -206,12 +207,12 @@ The Manifest files can specify the following tags:
   verification (always pass). *Path* must be a plain file or directory
   path without a trailing slash, and must not contain wildcards.
 
-``DATA <path> <size> <checksums>…``
+``DATA <path> <size> <checksums>...``
   Specifies a regular file subject to Manifest verification. The file
   is required to pass verification. Used for all files that do not match
   any other type.
 
-``DIST <filename> <size> <checksums>…``
+``DIST <filename> <size> <checksums>...``
   Specifies a distfile entry used to verify files fetched as part
   of ``SRC_URI``. The filename must match the filename used to store
   the fetched file as specified in the PMS [#PMS-FETCH]_. The package
@@ -226,15 +227,15 @@ Deprecated Manifest tags
 For backwards compatibility, the following tags are additionally
 allowed at the package directory level:
 
-``EBUILD <filename> <size> <checksums>…``
+``EBUILD <filename> <size> <checksums>...``
   Equivalent to the ``DATA`` type.
 
-``MISC <path> <size> <checksums>…``
+``MISC <path> <size> <checksums>...``
   Equivalent to the ``DATA`` type. Historically indicated that
   the package manager may ignore a verification failure if operating
   in non-strict mode. However, that behavior is deprecated.
 
-``AUX <filename> <size> <checksums>…``
+``AUX <filename> <size> <checksums>...``
   Equivalent to the ``DATA`` type, except that the filename is relative
   to ``files/`` subdirectory.
 
@@ -314,13 +315,13 @@ of supported algorithms is outside the scope of this specification.
 The algorithm names reserved at the time of writing are:
 
 - ``MD5`` [#MD5]_,
-- ``RMD160`` — RIPEMD-160 [#RIPEMD160]_,
+- ``RMD160`` -- RIPEMD-160 [#RIPEMD160]_,
 - ``SHA1`` [#SHS]_,
-- ``SHA256`` and ``SHA512`` — SHA-2 family of hashes [#SHS]_,
+- ``SHA256`` and ``SHA512`` -- SHA-2 family of hashes [#SHS]_,
 - ``WHIRLPOOL`` [#WHIRLPOOL]_,
-- ``BLAKE2B`` and ``BLAKE2S`` — BLAKE2 family of hashes [#BLAKE2]_,
-- ``SHA3_256`` and ``SHA3_512`` — SHA-3 family of hashes [#SHA3]_,
-- ``STREEBOG256`` and ``STREEBOG512`` — Streebog family of hashes
+- ``BLAKE2B`` and ``BLAKE2S`` -- BLAKE2 family of hashes [#BLAKE2]_,
+- ``SHA3_256`` and ``SHA3_512`` -- SHA-3 family of hashes [#SHA3]_,
+- ``STREEBOG256`` and ``STREEBOG512`` -- Streebog family of hashes
   [#STREEBOG]_.
 
 The method of introducing new hashes is defined by GLEP 59 [#GLEP59]_.
@@ -370,9 +371,9 @@ the following content::
     IGNORE lost+found
     IGNORE packages
     MANIFEST app-accessibility/Manifest 14821 SHA256 1b5f.. SHA512 f7eb..
-    …
+    ...
     MANIFEST eclass/Manifest.gz 50812 SHA256 8c55.. SHA512 2915..
-    …
+    ...
 
 An example modern Manifest (disregarding backwards compatibility)
 for a package directory would have the following content::
@@ -484,15 +485,17 @@ files, and symbolic links to directories are followed as if they were
 regular directories.
 
 Dotfiles are implicitly ignored as that is a common notion used
-in software written for POSIX systems. All other common filenames
-require explicit ``IGNORE`` lines.
+in software written for POSIX systems. All other filenames require
+explicit ``IGNORE`` lines.
 
 An ability to inject additional ignore entries is provided to account
-for site configuration affecting the repository tree — placing
+for site configuration affecting the repository tree -- placing
 additional files in it, skipping some of the categories from syncing.
+This configuration can extend beyond the limits of this GLEP,
+e.g. by allowing wildcards or regular expressions.
 
 The algorithm is restricted to work on a single filesystem. This is
-mostly relevant when scanning for top-level Manifest — we do not want
+mostly relevant when scanning for top-level Manifest -- we do not want
 to cross filesystem boundaries then. However, to ensure consistent
 bidirectional behavior we need to also ban them when operating downwards
 the tree.
@@ -551,9 +554,11 @@ However, the usefulness of ``MISC`` in both cases is doubtful.
 The cases for stripping unnecessary files mostly focused around space
 savings. For this purpose, stripping ``metadata.xml`` and similar files
 has little value. It is much more common for users to strip whole
-categories which can not be handled via the ``MISC`` type, and needs
-a dedicated package manager mechanism. The same mechanism can also
-handle files that used the ``MISC`` type.
+packages or categories. The ``MISC`` type is not suitable for that,
+and so a dedicated package manager mechanism needs to be developed
+instead; possibly combining it with rsync exclusion list. The same
+mechanism can also handle files that historically used the ``MISC``
+type.
 
 The cases for autogenerated files involve such cache files
 as ``use.local.desc``. However, we can not include ``md5-cache`` there
@@ -673,8 +678,8 @@ in a single file inside the package directory. It has been specifically
 pointed out that:
 
 - since distfiles are sometimes reused across different packages,
-  the repeating checksums are redundant,
-
+  the repeating checksums are redundant [#DIST]_.
+  
 - mirror admins were interested in the possibility of verifying all
   the distfiles with a single tool.
 
@@ -833,7 +838,7 @@ References
 .. [#WHIRLPOOL] The WHIRLPOOL Hash Function
    (http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html)
 
-.. [#BLAKE2] BLAKE2 — fast secure hashing
+.. [#BLAKE2] BLAKE2 -- fast secure hashing
    (https://blake2.net/)
 
 .. [#SHA3] FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash
@@ -846,6 +851,10 @@ References
 .. [#C08] Cappos, J et al. (2008). "Attacks on Package Managers"
    (https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html)
 
+.. [#DIST] According to Robin H. Johnson, 8.4% of all DIST entries
+   at the time of writing are duplicate, representing a 2 MiB
+   out of 25 MiB of DIST entries altogether.
+
 .. [#GEMATO] gemato: Gentoo Manifest Tool
    (https://github.com/mgorny/gemato/)