1 |
commit: 85a30b31496898b73dbdb06c4ffb665dad23b653 |
2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
3 |
AuthorDate: Thu Nov 2 19:08:12 2017 +0000 |
4 |
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Nov 13 16:33:01 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=85a30b31 |
7 |
|
8 |
glep-0074: Further cleanup |
9 |
|
10 |
glep-0074.rst | 73 ++++++++++++++++++++++++++++++++++------------------------- |
11 |
1 file changed, 42 insertions(+), 31 deletions(-) |
12 |
|
13 |
diff --git a/glep-0074.rst b/glep-0074.rst |
14 |
index eee863a..e4d6a80 100644 |
15 |
--- a/glep-0074.rst |
16 |
+++ b/glep-0074.rst |
17 |
@@ -96,13 +96,17 @@ covered by a signed top-level Manifest. |
18 |
Directory tree coverage |
19 |
----------------------- |
20 |
|
21 |
-The Manifest files can also specify ``IGNORE`` entries to skip Manifest |
22 |
-verification of subdirectories and/or files. The package manager can |
23 |
-support injecting ignore paths to account for additional files created, |
24 |
-modified or removed by user's processes that would not be ignored |
25 |
-by existing rules. Files and directories starting with a dot are always |
26 |
-implicitly ignored. All files that are not ignored must be covered |
27 |
-by at least one of the Manifests. |
28 |
+The specification provides three ways of skipping Manifest verification |
29 |
+of specific files and directories (recursively): |
30 |
+ |
31 |
+1. explicit ``IGNORE`` entries in Manifest files, |
32 |
+ |
33 |
+2. injected ignore paths via package manager configuration, |
34 |
+ |
35 |
+3. using names starting with a dot (``.``) which are always skipped. |
36 |
+ |
37 |
+All files that are not ignored must be covered by at least one |
38 |
+of the Manifests. |
39 |
|
40 |
A single file may be matched by multiple identical or equivalent |
41 |
Manifest entries, if and only if the entries have the same semantics, |
42 |
@@ -113,14 +117,17 @@ to specify another entry for a file matching ``IGNORE``, or one of its |
43 |
subdirectories. |
44 |
|
45 |
The file entries (except for ``IGNORE``) can be specified for regular |
46 |
-files only. Symbolic links are followed when opening files. It is |
47 |
-an error to specify an entry for a different file type. |
48 |
+files only. Symbolic links are followed when opening files |
49 |
+and traversing directories. It is an error to specify an entry for |
50 |
+a different file type. If the tree contain files of other types |
51 |
+that are not otherwise ignored, they need to be covered by an explicit |
52 |
+``IGNORE``. |
53 |
|
54 |
All the local (non-``DIST``) files covered by a Manifest tree must |
55 |
reside on the same filesystem. It is an error to specify entries |
56 |
applying to files on another filesystem. If subdirectories |
57 |
-of the Manifest tree reside on a different filesystem, they must |
58 |
-be explicitly excluded via ``IGNORE``. |
59 |
+that are not otherwise ignored reside on a different filesystem, they |
60 |
+must be explicitly excluded via ``IGNORE``. |
61 |
|
62 |
|
63 |
File verification |
64 |
@@ -196,7 +203,8 @@ The Manifest files can specify the following tags: |
65 |
``IGNORE <path>`` |
66 |
Ignores a subdirectory or file from Manifest checks. If the specified |
67 |
path is present, it and its contents are omitted from the Manifest |
68 |
- verification (always pass). |
69 |
+ verification (always pass). *Path* must be a plain file or directory |
70 |
+ path without a trailing slash, and must not contain wildcards. |
71 |
|
72 |
``DATA <path> <size> <checksums>…`` |
73 |
Specifies a regular file subject to Manifest verification. The file |
74 |
@@ -362,9 +370,9 @@ the following content:: |
75 |
IGNORE lost+found |
76 |
IGNORE packages |
77 |
MANIFEST app-accessibility/Manifest 14821 SHA256 1b5f.. SHA512 f7eb.. |
78 |
- ... |
79 |
+ … |
80 |
MANIFEST eclass/Manifest.gz 50812 SHA256 8c55.. SHA512 2915.. |
81 |
- ... |
82 |
+ … |
83 |
|
84 |
An example modern Manifest (disregarding backwards compatibility) |
85 |
for a package directory would have the following content:: |
86 |
@@ -476,8 +484,12 @@ files, and symbolic links to directories are followed as if they were |
87 |
regular directories. |
88 |
|
89 |
Dotfiles are implicitly ignored as that is a common notion used |
90 |
-in software written for POSIX systems. All other filenames require |
91 |
-explicit ``IGNORE`` lines. |
92 |
+in software written for POSIX systems. All other common filenames |
93 |
+require explicit ``IGNORE`` lines. |
94 |
+ |
95 |
+An ability to inject additional ignore entries is provided to account |
96 |
+for site configuration affecting the repository tree — placing |
97 |
+additional files in it, skipping some of the categories from syncing. |
98 |
|
99 |
The algorithm is restricted to work on a single filesystem. This is |
100 |
mostly relevant when scanning for top-level Manifest — we do not want |
101 |
@@ -485,7 +497,7 @@ to cross filesystem boundaries then. However, to ensure consistent |
102 |
bidirectional behavior we need to also ban them when operating downwards |
103 |
the tree. |
104 |
|
105 |
-The directories and files on different filesystems needs to be ignored |
106 |
+The directories and files on different filesystems need to be ignored |
107 |
explicitly as implicitly skipping them would cause confusion. |
108 |
In particular, tools might then claim that a file does not exist when |
109 |
it clearly does because it was skipped due to filesystem boundaries. |
110 |
@@ -736,26 +748,25 @@ Backwards Compatibility |
111 |
======================= |
112 |
|
113 |
This GLEP provides optional means of preserving backwards compatibility. |
114 |
-To preserve the backwards compatibility, the following needs to be |
115 |
-ensured: |
116 |
+To preserve the backwards compatibility, the following needs to hold |
117 |
+for the ``Manifest`` file in every package directory: |
118 |
+ |
119 |
+- all files must be covered by the single ``Manifest`` file, |
120 |
|
121 |
-- all files within the package directory must be covered by ``Manifest`` |
122 |
- file inside that package directory, |
123 |
+- all distfiles used by the package must be included, |
124 |
|
125 |
-- all distfiles used by the package must be covered by ``Manifest`` |
126 |
- file inside the package directory, |
127 |
+- all files inside the ``files/`` subdirectory need to use |
128 |
+ the ``AUX`` tag (rather than ``DATA``), |
129 |
|
130 |
-- all files inside the ``files/`` subdirectory of a package directory |
131 |
- need to be use the deprecated ``AUX`` tag (rather than ``DATA``), |
132 |
+- all ``.ebuild`` files need to use the ``EBUILD`` tag, |
133 |
|
134 |
-- all ``.ebuild`` files inside the package directory need to use |
135 |
- the deprecated ``EBUILD`` tag (rather than ``DATA``), |
136 |
+` the ``metadata.xml`` and ``ChangeLog`` files need to use |
137 |
+ the ``MISC`` tag, |
138 |
|
139 |
-- the Manifest files inside the package directory can be signed |
140 |
- to provide authenticity verification, |
141 |
+- the Manifest can be signed to provide authenticity verification, |
142 |
|
143 |
-- an uncompressed Manifest file must exist in the package directory, |
144 |
- and a compressed Manifest of identical content may be present. |
145 |
+- an uncompressed Manifest must always exist, and a compressed Manifest |
146 |
+ of identical content may be present. |
147 |
|
148 |
Once the backwards compatibility is no longer a concern, the above |
149 |
no longer needs to hold and the deprecated tags can be removed. |