From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 20E3D139084 for ; Sat, 25 Nov 2017 20:49:43 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 92397E0E56; Sat, 25 Nov 2017 20:49:39 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 64A4BE0E56 for ; Sat, 25 Nov 2017 20:49:39 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id EDB3333C770 for ; Sat, 25 Nov 2017 20:49:37 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 06C14A77C for ; Sat, 25 Nov 2017 20:49:35 +0000 (UTC) From: "Michał Górny" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Michał Górny" Message-ID: <1511642955.6af470fce9e2a8b798691d788903e6f0ca9e140d.mgorny@gentoo> Subject: [gentoo-commits] data/glep:master commit in: / X-VCS-Repository: data/glep X-VCS-Files: glep-0074.rst X-VCS-Directories: / X-VCS-Committer: mgorny X-VCS-Committer-Name: Michał Górny X-VCS-Revision: 6af470fce9e2a8b798691d788903e6f0ca9e140d X-VCS-Branch: master Date: Sat, 25 Nov 2017 20:49:35 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: c65808de-8a63-441a-bc11-a5bf15ce085b X-Archives-Hash: a0f3871826af98433673aebc5d2e064f commit: 6af470fce9e2a8b798691d788903e6f0ca9e140d Author: Michał Górny gentoo org> AuthorDate: Thu Nov 2 19:08:12 2017 +0000 Commit: Michał Górny gentoo org> CommitDate: Sat Nov 25 20:49:15 2017 +0000 URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=6af470fc glep-0074: Further cleanup glep-0074.rst | 73 ++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/glep-0074.rst b/glep-0074.rst index eee863a..e4d6a80 100644 --- a/glep-0074.rst +++ b/glep-0074.rst @@ -96,13 +96,17 @@ covered by a signed top-level Manifest. Directory tree coverage ----------------------- -The Manifest files can also specify ``IGNORE`` entries to skip Manifest -verification of subdirectories and/or files. The package manager can -support injecting ignore paths to account for additional files created, -modified or removed by user's processes that would not be ignored -by existing rules. Files and directories starting with a dot are always -implicitly ignored. All files that are not ignored must be covered -by at least one of the Manifests. +The specification provides three ways of skipping Manifest verification +of specific files and directories (recursively): + +1. explicit ``IGNORE`` entries in Manifest files, + +2. injected ignore paths via package manager configuration, + +3. using names starting with a dot (``.``) which are always skipped. + +All files that are not ignored must be covered by at least one +of the Manifests. A single file may be matched by multiple identical or equivalent Manifest entries, if and only if the entries have the same semantics, @@ -113,14 +117,17 @@ to specify another entry for a file matching ``IGNORE``, or one of its subdirectories. The file entries (except for ``IGNORE``) can be specified for regular -files only. Symbolic links are followed when opening files. It is -an error to specify an entry for a different file type. +files only. Symbolic links are followed when opening files +and traversing directories. It is an error to specify an entry for +a different file type. If the tree contain files of other types +that are not otherwise ignored, they need to be covered by an explicit +``IGNORE``. 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 -of the Manifest tree reside on a different filesystem, they must -be explicitly excluded via ``IGNORE``. +that are not otherwise ignored reside on a different filesystem, they +must be explicitly excluded via ``IGNORE``. File verification @@ -196,7 +203,8 @@ The Manifest files can specify the following tags: ``IGNORE `` Ignores a subdirectory or file from Manifest checks. If the specified path is present, it and its contents are omitted from the Manifest - verification (always pass). + verification (always pass). *Path* must be a plain file or directory + path without a trailing slash, and must not contain wildcards. ``DATA …`` Specifies a regular file subject to Manifest verification. The file @@ -362,9 +370,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:: @@ -476,8 +484,12 @@ 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 filenames require -explicit ``IGNORE`` lines. +in software written for POSIX systems. All other common filenames +require explicit ``IGNORE`` lines. + +An ability to inject additional ignore entries is provided to account +for site configuration affecting the repository tree — placing +additional files in it, skipping some of the categories from syncing. The algorithm is restricted to work on a single filesystem. This is mostly relevant when scanning for top-level Manifest — we do not want @@ -485,7 +497,7 @@ to cross filesystem boundaries then. However, to ensure consistent bidirectional behavior we need to also ban them when operating downwards the tree. -The directories and files on different filesystems needs to be ignored +The directories and files on different filesystems need to be ignored explicitly as implicitly skipping them would cause confusion. In particular, tools might then claim that a file does not exist when it clearly does because it was skipped due to filesystem boundaries. @@ -736,26 +748,25 @@ Backwards Compatibility ======================= This GLEP provides optional means of preserving backwards compatibility. -To preserve the backwards compatibility, the following needs to be -ensured: +To preserve the backwards compatibility, the following needs to hold +for the ``Manifest`` file in every package directory: + +- all files must be covered by the single ``Manifest`` file, -- all files within the package directory must be covered by ``Manifest`` - file inside that package directory, +- all distfiles used by the package must be included, -- all distfiles used by the package must be covered by ``Manifest`` - file inside the package directory, +- all files inside the ``files/`` subdirectory need to use + the ``AUX`` tag (rather than ``DATA``), -- all files inside the ``files/`` subdirectory of a package directory - need to be use the deprecated ``AUX`` tag (rather than ``DATA``), +- all ``.ebuild`` files need to use the ``EBUILD`` tag, -- all ``.ebuild`` files inside the package directory need to use - the deprecated ``EBUILD`` tag (rather than ``DATA``), +` the ``metadata.xml`` and ``ChangeLog`` files need to use + the ``MISC`` tag, -- the Manifest files inside the package directory can be signed - to provide authenticity verification, +- the Manifest can be signed to provide authenticity verification, -- an uncompressed Manifest file must exist in the package directory, - and a compressed Manifest of identical content may be present. +- an uncompressed Manifest must always exist, and a compressed Manifest + of identical content may be present. Once the backwards compatibility is no longer a concern, the above no longer needs to hold and the deprecated tags can be removed.