1 |
commit: a0b5ca20ae53c8867b45d734cfe25d31de738dbe |
2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
3 |
AuthorDate: Tue Oct 17 18:04:37 2017 +0000 |
4 |
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Nov 13 16:07:56 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=a0b5ca20 |
7 |
|
8 |
glep-0065: Provide post-postinst QA checks |
9 |
|
10 |
glep-0065.rst | 139 +++++++++++++++++++++++++++++++++++++--------------------- |
11 |
1 file changed, 89 insertions(+), 50 deletions(-) |
12 |
|
13 |
diff --git a/glep-0065.rst b/glep-0065.rst |
14 |
index e628184..a8a7321 100644 |
15 |
--- a/glep-0065.rst |
16 |
+++ b/glep-0065.rst |
17 |
@@ -4,22 +4,23 @@ Title: Post-install QA checks |
18 |
Author: Michał Górny <mgorny@g.o> |
19 |
Type: Standards Track |
20 |
Status: Draft |
21 |
-Version: 1 |
22 |
+Version: 2 |
23 |
Created: 2014-10-26 |
24 |
-Last-Modified: 2014-12-14 |
25 |
-Post-History: 2014-10-30 |
26 |
+Last-Modified: 2017-10-17 |
27 |
+Post-History: 2014-10-30, 2017-10-17 |
28 |
Content-Type: text/x-rst |
29 |
--- |
30 |
|
31 |
Abstract |
32 |
======== |
33 |
|
34 |
-This GLEP provides a mechanism for running QA checks on installation image |
35 |
-after ``src_install`` phase exits. The checks can be provided by the Package |
36 |
-Manager, repositories, packages (installed system-wide) and the system |
37 |
-administrator. The QA checks can inspect the installation image, output and |
38 |
-store both user- and machine-oriented QA warning logs, manipulate the files |
39 |
-and abort the install, as necessary. |
40 |
+This GLEP provides two kinds of QA check: checks run on the installation image |
41 |
+once ``src_install`` returns, and checks run on the live system once |
42 |
+``pkg_postinst`` returns. The checks can be provided by the Package Manager, |
43 |
+repositories, packages (installed system-wide) and the system administrator. |
44 |
+The QA checks can inspect the installation image or live system respectively, |
45 |
+output and store both user- and machine-oriented QA warning logs, manipulate |
46 |
+the files and abort the install, as necessary. |
47 |
|
48 |
|
49 |
Motivation |
50 |
@@ -39,7 +40,7 @@ eclass uses. Some of the checks depend on external tools being present. |
51 |
Keeping those checks directly in Portage sources has two major disadvantages: |
52 |
|
53 |
1. The checks can not be properly updated without Portage upgrade. |
54 |
- In particular, a change in QA check becomes fully effective when |
55 |
+ In particular, a change in a QA check becomes fully effective when |
56 |
the relevant Portage version becomes stable and the user upgrades. |
57 |
There is no easy way to keep QA checks in sync with eclasses. |
58 |
|
59 |
@@ -50,14 +51,41 @@ Keeping those checks directly in Portage sources has two major disadvantages: |
60 |
Specification |
61 |
============= |
62 |
|
63 |
-QA check format & locations |
64 |
---------------------------- |
65 |
+QA check types |
66 |
+-------------- |
67 |
+ |
68 |
+There are two kinds of QA checks defined in this specification: |
69 |
+ |
70 |
+1. Post-install QA checks (``install-qa-check.d``), |
71 |
+ |
72 |
+2. Post-merge (postinst) QA checks (``postinst-qa-check.d``). |
73 |
+ |
74 |
+The post-install QA checks are are executed after the ``src_install`` ebuild |
75 |
+phase finishes but before the binary package is built or the ``pkg_preinst`` |
76 |
+phase is executed. They can use the same commands as are permitted |
77 |
+in ``src_install``, and access the installation image ``${D}`` |
78 |
+and the temporary directory ``${T}``. |
79 |
+ |
80 |
+In case of severe QA issues, the checks are allowed to alter the contents of |
81 |
+the installation image in order to sanitize them, or call the ``die`` function |
82 |
+to abort the build. |
83 |
+ |
84 |
+The post-merge QA checks are executed after the ``pkg_postinst`` ebuild phase |
85 |
+finishes. They can use the same commands as are permitted in ``pkg_postinst``, |
86 |
+and access the installed system location ``${ROOT}`` and the temporary |
87 |
+directory ``${T}``. |
88 |
+ |
89 |
+The checks are allowed to alter the contents of the filesystem to the same |
90 |
+degree as ``pkg_postinst`` phase is. They must not call ``die``. |
91 |
+ |
92 |
+QA check file format & locations |
93 |
+-------------------------------- |
94 |
|
95 |
QA checks are stored as bash scripts. The checks are identified and ordered |
96 |
by file name. If files with same names are present in multiple locations, |
97 |
the file in location with the highest priority is used. |
98 |
|
99 |
-The specification defines four types of QA checks, listed in the order |
100 |
+The specification defines four sources of QA checks, listed in the order |
101 |
of increasing priority: |
102 |
|
103 |
1. internal checks included in the Package Manager, |
104 |
@@ -71,13 +99,15 @@ generic checks are included in the Package Manager and not checks specific to |
105 |
Gentoo policies, packages or eclasses included in Gentoo. |
106 |
|
107 |
Repository-specific QA checks are included in ``metadata/install-qa-check.d`` |
108 |
-directory of a repository. For an ebuild in question, the repository |
109 |
-containing it and its masters are traversed for QA checks, with priority |
110 |
-decreasing with each inheritance level. |
111 |
+and ``metadata/postinst-qa-check.d`` directories of a repository. |
112 |
+For an ebuild in question, the repository containing it and its masters are |
113 |
+traversed for QA checks, with priority decreasing with each inheritance level. |
114 |
|
115 |
The package-installed QA checks are located in ``/usr/lib/install-qa-check.d`` |
116 |
-and are intended to be installed by packages. The sysadmin-defined QA checks |
117 |
-are located in ``/usr/local/lib/install-qa-check.d``. |
118 |
+and ``/usr/lib/postinst-qa-check.d``, and are intended to be installed |
119 |
+by packages. The sysadmin-defined QA checks are located |
120 |
+in ``/usr/local/lib/install-qa-check.d`` |
121 |
+and ``/usr/local/lib/postinst-qa-check.d``. |
122 |
|
123 |
QA check script format |
124 |
---------------------- |
125 |
@@ -87,19 +117,11 @@ run in an isolated subshell, and therefore can safely alter the environment |
126 |
and change the working directory. QA scripts must always end with a command |
127 |
terminating with a successful exit code. |
128 |
|
129 |
-The QA checks are executed after the ``src_install`` ebuild phase finishes |
130 |
-and before the binary package is built or the ``pkg_preinst`` phase is |
131 |
-executed. They can use the same commands as allowed in ``src_install``, |
132 |
-and use the installation image ``${D}`` and the temporary directory ``${T}``. |
133 |
-Aside to standard PMS functions, two additional commands are provided: |
134 |
+Aside to the standard PMS functions, two additional commands are provided: |
135 |
|
136 |
1. ``eqawarn`` to output QA warnings to user, |
137 |
2. ``eqatag`` to store machine-readable information about QA issues. |
138 |
|
139 |
-In case of severe QA issues, the checks are allowed to alter the contents of |
140 |
-the installation image in order to sanitize them, or call the ``die`` function |
141 |
-to abort the build. |
142 |
- |
143 |
Repository-defined QA checks are allowed to ``inherit`` eclasses from |
144 |
the repository providing the check or any of its masters. The same |
145 |
inheritance rules apply as to ebuilds in the particular repository. Sourced |
146 |
@@ -147,37 +169,54 @@ the tags used by ``60bash-completion`` check would be named |
147 |
Rationale |
148 |
========= |
149 |
|
150 |
-QA check format & locations |
151 |
---------------------------- |
152 |
+QA check types |
153 |
+-------------- |
154 |
+ |
155 |
+The two types of QA checks were created to account for different kinds |
156 |
+of common mistakes in ebuilds. |
157 |
+ |
158 |
+Post-install QA checks can be used to verify the installation image before |
159 |
+it is merged to a live system or published as a binary package. They can |
160 |
+account for various problems caused by the ebuild code up to and including |
161 |
+``src_install``, the upstream code executed as part of any of those phases |
162 |
+and the supplied files. |
163 |
+ |
164 |
+Post-postinst QA checks can be used to verify the state of system after |
165 |
+the package is merged and its ``pkg_postinst`` phase is executed. They mostly |
166 |
+aim to detect missing postinst actions but can do other live system integrity |
167 |
+checks. |
168 |
+ |
169 |
+QA check file format & locations |
170 |
+-------------------------------- |
171 |
|
172 |
The multiple locations for QA checks aim to get the best coverage for various |
173 |
requirements. |
174 |
|
175 |
-The checks installed along with the Package Manager are meant to cover the |
176 |
-generic cases and other checks that rely on Package Manager internals. Unlike |
177 |
-other categories of QA checks, those checks apply to a single Package Manager |
178 |
-only and can therefore use internal API. However, it is recommended that this |
179 |
-category is used scarcely. |
180 |
+The checks installed along with the Package Manager are meant to cover |
181 |
+the generic cases and other checks that rely on Package Manager internals. |
182 |
+Unlike other categories of QA checks, those checks apply to a single Package |
183 |
+Manager only and can therefore use internal API. However, it is recommended |
184 |
+that this category is used scarcely. |
185 |
|
186 |
Storing checks in the repository allows developers to strictly bind them to |
187 |
a specific version of the distribution and update them along with the relevant |
188 |
-policies and/or eclasses. In particular, rules enforced by Gentoo policies and |
189 |
-eclasses don't have to apply to other distributions using Portage. |
190 |
+policies and/or eclasses. In particular, rules enforced by Gentoo policies |
191 |
+and eclasses don't have to apply to other distributions using Portage. |
192 |
|
193 |
The QA checks are applied to sub-repositories (via ``masters`` attribute) |
194 |
-likewise eclasses. This makes sure that the common repositories don't lose QA |
195 |
-checks. The QA checks related to eclasses are inherited the same way as |
196 |
-eclasses are. Similarly to eclasses, sub-repositories can override (or |
197 |
-disable) QA checks. |
198 |
+likewise eclasses. This makes sure that the majority of repositories don't |
199 |
+lose QA checks. The QA checks related to eclasses are inherited the same way |
200 |
+as eclasses are. Similarly to eclasses, sub-repositories can override |
201 |
+(or disable) QA checks. |
202 |
|
203 |
System-wide QA checks present the opportunity of installing QA checks along |
204 |
with packages. In the past, some QA checks were run only conditionally |
205 |
-depending on existence of external checker software. Instead, the software can |
206 |
-install its own QA checks directly. |
207 |
+depending on existence of external checker software. Instead, the software |
208 |
+packages can install their own QA checks directly. |
209 |
|
210 |
-The administrative override via ``/usr/local`` is a natural extension of |
211 |
-system-wide QA checks. Additionally, it can be used by the sysadmin to |
212 |
-override or disable practically any other QA check, either internal Portage |
213 |
+The administrative override via ``/usr/local`` is a natural extension |
214 |
+of system-wide QA checks. Additionally, it can be used by the sysadmin |
215 |
+to override or disable practically any other QA check, either internal Portage |
216 |
or repository-wide. |
217 |
|
218 |
Sharing the QA checks has the additional advantage of having unified QA tools |
219 |
@@ -186,9 +225,8 @@ for all Package Managers. |
220 |
QA check script format |
221 |
---------------------- |
222 |
|
223 |
-Use of bash is aimed to match the ebuild format at ''src_install'' phase. |
224 |
-The choice of functions aims at providing portability between Package |
225 |
-Managers. |
226 |
+Use of bash is aimed to match the ebuild format. The choice of functions aims |
227 |
+at portability between Package Managers. |
228 |
|
229 |
The scripts are run in isolated subshell to simplify the checks and reduce |
230 |
the risk of accidental cross-script issues. |
231 |
@@ -289,8 +327,9 @@ be used from the repository anyway. |
232 |
Reference implementation |
233 |
======================== |
234 |
|
235 |
-The reference implementation is available in Portage starting with version |
236 |
-2.2.15 (released 2014-12-04). |
237 |
+The reference implementation of ``install-qa-check.d`` is available in Portage |
238 |
+starting with version 2.2.15 (released 2014-12-04). The support |
239 |
+for ``postinst-qa-check.d`` was added in 2.3.9 (released 2017-09-19). |
240 |
|
241 |
|
242 |
Copyright |