1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
|
<?xml version="1.0"?>
<guide self="keywording/">
<chapter>
<title>Keywording and Stabilization</title>
<body>
<note>
<e>Terminology</e>: The term 'package' refers to an entire directory, for
example <c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific
version. The terms 'ebuild' or 'package version' are used when this meaning is
intended. This distinction is important.
</note>
<p>
Most ebuilds specify a <c>KEYWORDS</c> variable. This variable is used to
indicate the suitability and stability of both the package and the ebuild on
each given arch (<c>sparc</c>, <c>ppc</c>, <c>x64-macos</c>, ...).
</p>
<note>
The term 'arch' is used in this sense for historical reasons. As a result
of <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri>
and the various non-Linux ports, this is no longer a particularly
accurate term.
</note>
<p>
A sample <c>KEYWORDS</c> entry might look like:
</p>
<codesample lang="ebuild">
KEYWORDS="-ia64 ~mips ~ppc sparc x86 ~ppc-macos"
</codesample>
<p>
The different levels of keyword are:
</p>
<dl>
<dt>
<c>arch</c> (<c>x86</c>, <c>ppc-macos</c>) ("stable")
</dt>
<dd>
Both the package version <e>and</e> the ebuild are widely tested, known to
work and not have any serious issues on the indicated platform.
</dd>
<dt>
<c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>) ("testing")
</dt>
<dd>
The package version and the ebuild are believed to work and do not have any
known serious bugs, but more testing is required before the package version
is considered suitable for <c>arch</c>.
</dd>
<dt>
No keyword ("unkeyworded")
</dt>
<dd>
If a package has no keyword for a given arch, it means it is not known
whether the package will work, or that insufficient testing has occurred for
<c>~arch</c>.
</dd>
<dt>
<c>-arch</c> (<c>-x86</c>, <c>-ppc-macos</c>)
</dt>
<dd>
The package version will not work on the arch. This could be caused by badly
written code (for example, non-64-bit or endian clean code), relying upon
particular hardware (for example, a BIOS querying tool would not work on
non-BIOS architectures) or binary only packages.
</dd>
</dl>
<p>
The <c>-*</c> keyword is special. It is used to indicate package versions which
are not worth trying to test on unlisted arches. For example, a binary-only
package which is only supported upstream on <c>ppc</c> and <c>x86</c> might
use:
</p>
<codesample lang="ebuild">
KEYWORDS="-* ppc x86"
</codesample>
<p>
This is different in implication from <c>"ppc x86"</c> <d/> the former implies
that it will not work on other arches, whereas the latter implies that it has
not been tested.
</p>
<p>
Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds.
</p>
<note>
Usually, "live" ebuilds
(see <uri link="::ebuild-writing/functions/src_unpack/vcs-sources/"/>)
do not specify a <c>KEYWORDS</c> variable.
</note>
</body>
<section>
<title>Equal Visibility Requirement</title>
<body>
<p>
An ebuild <b>must not</b> depend upon any package that is of a lower keyword
level than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>,
and <c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked
stable on <c>x86</c> unless <c>bar-1.2</c> is also stabilised.
</p>
<p>
You may assume that if a user accepts <c>~arch</c> for a given arch then they
also accept <c>arch</c>.
</p>
<p>
For optional dependencies, all <e>possible</e> dependencies must satisfy the
above. Note that certain <c>USE</c> flags can be forcibly disabled on a
per-profile basis <d /> talk to the arch teams if you require this. For
either-or dependencies, <e>at least one</e> of the options must be of equal or
better visibility than the package in question.
</p>
</body>
</section>
<section>
<title>Hard Masks</title>
<body>
<p>
The <c>package.mask</c> file can be used to 'hard mask' individual or groups of
ebuilds. This should be used for testing ebuilds or beta releases of software,
and may also be used if a package has serious compatibility problems. Packages
which are not hard masked must <b>not</b> have a dependency upon hard masked
packages.
</p>
<p>
It is good practice to file a bug for ebuilds listed in <c>package.mask</c> to
allow feedback to be gathered in one location and to reduce the chance of
forgetting about it. Mention the bug number in the mask message.
</p>
<p>
The only time it is acceptable for a user to see the <c>Possibly a DEPEND
problem</c> error message is if they have manually changed visibility levels for
a package (for example, through <c>/etc/portage/</c>) and have missed a
dependency. <b>You should never commit a change which could cause this error to
appear on a user system</b>.
</p>
</body>
</section>
<section>
<title>Keywording New Packages</title>
<body>
<important>
New packages should be marked as <c>~arch</c> ("testing") only upon
architectures for which the committing developer has tested. If proxying
commits for a non-developer, please ensure they have some relationship
with the relevant arch teams, or <d/> better yet <d/> ask them to file
a keywording bug instead for non-<c>amd64</c>/<c>x86</c>.
</important>
<p>
Do <b>not</b> assume that your package works on all architectures. Do <b>not</b>
assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d />
chances are they just copied from somewhere else. Do <b>not</b> assume that
upstream's 'supported architectures' list is correct. Do <b>not</b> assume that
because your code is written in Perl / Python / Java / whatever that it will run
on other arches (there is at least one case of a <c>vim</c> script which only
worked on <c>x86</c>).
</p>
<p>
Note that most (non-<c>amd64</c>/<c>x86</c>) arches expect you to be on the
arch team and bugzilla alias if you are committing packages with keywords for
that arch, and may have additional requirements of which you should be aware
(on <c>mips</c>, for example, there are multiple ABIs and byte orders to
consider <d/> a package working on your <c>o32</c> box may not work on
<c>o64</c> or <c>n32</c>). Contact the individual arch teams for details.
</p>
<p>
It's important to note that alternative arches (like <c>alpha</c>, <c>ia64</c>,
<c>s390</c>, <c>sparc</c>, <c>hppa</c>, <c>ppc*</c>) are mainly understaffed
arches, some of them are slow, they have more basic problems and have a small
userbase. Just file bugs for these architectures when a package is going to be
a dependency of a package already keyworded.
</p>
<p>
Do <b>not</b> commit straight to <c>arch</c> ("stable"). If it is necessary
to do so, when using <c>repoman</c>, use
<c>repoman commit --straight-to-stable</c> and <b>not</b> <c>--force</c> as
this disables other QA checks.
</p>
</body>
</section>
<section>
<title>Keywording on Upgrades</title>
<body>
<p>
When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c>
("testing"), and leave any existing <c>~arch</c> keywords intact. It's easiest
and safest to use <c>ekeyword ~all my-new-version.ebuild</c> from the <c>
app-portage/gentoolkit</c> package. This must be done even if you <e>think</e>
you're just making a trivial fix <d /> there have been several examples of the
stable tree getting broken this way.
</p>
<p>
This also applies to revision bumps, not just to upstream version changes.
</p>
<p>
If a new version introduces new dependencies which are not available on some
architectures, then you should file a bug or ask on IRC before you upgrade the
ebuild. If you really need to get the ebuild added in a hurry, for example,
for a security fix, then you should drop any <c>KEYWORDS</c> which are causing
problems and CC the relevant architectures on the bug <d/> you <b>must</b> file
a <uri link="https://projects.gentoo.org/qa/policy-guide/keywords.html#pg0401">
new bug</uri> to the architecture in question regarding this if no bug is
already available.
</p>
<p>
If there are no new dependencies, do not remove keywords if your commit fails
with <c>repoman</c> or <c>pkgdev</c> <d/> instead please commit with
<c>repoman -I</c> and file a bug to the broken architecture, noting it in your
git commit message.
</p>
<important>
When committing, make sure that you reference any bugs in the commit message.
See <uri link="::ebuild-maintenance/git/#Git Commit Message Format"/> for how
to do this.
</important>
</body>
</section>
<section>
<title>Moving from <c>~arch</c> to <c>arch</c></title>
<body>
<p>
If a package has stable keywords, maintainers should regularly (subject to the
rules below) file stabilization bugs for their packages, ideally approximately
every 30 days after a new version is added. If a bug report for stabilization
is filed by somebody else, the maintainer should respond with an
acknowledgement ("ACK") if the ebuild is ready, and a negative
acknowledgement ("NAK") if not.
</p>
<p>
Previous stable keywords should not be dropped without good cause and it is
courteous to ping members of the relevant arch team first. Maintainers must not
drop stable keywords simply because they don't have access to a platform: this
is what Gentoo's arch teams are here for.
</p>
<p>
By convention, these bugs are assigned to package maintainers, but the only
action expected from maintainers is to acknowledge or reject the
stabilization rather than carry out additional testing on each required
architecture themselves.
</p>
<p>
Stabilization, i.e., moving an ebuild from <c>~arch</c> ("testing") to
<c>arch</c> ("stable"), is done by the relevant architecture teams. If you have
access to exotic hardware but are not on the arch teams, you may wish to make
individual arrangements <d/> the arch teams are happy for help, so long as they
know what is going on.
</p>
<p>
In order to request stabilization of an ebuild, file a bug to the package's
maintainer (which may be yourself) in the Stabilization component, and list
all secondary maintainers in the bug's CC. When the maintainers consider the
ebuild to be ready for stabilization, they will add the relevant architecture
teams to the CC list. They can fill the package
list field, add the <c>CC-ARCHES</c> keyword, and let
<uri link="https://dev.gentoo.org/~mgorny/doc/nattka/">NATTkA</uri>
automatically add arch teams to CC (preferred), or do this manually.
That way, teams can remove themselves from the list when they are done, giving
a clear indication of which teams still remain to stabilize a package.
</p>
<p>
It is <e>strongly</e>
<uri link="https://archives.gentoo.org/gentoo-dev/message/cd62f6be924f6a0f76b68a07d33b256a">
recommended</uri> that <c>NATTkA</c> be used to file keywording or
stabilization bugs to ensure that arches are not accidentally forgot about;
the automation removes an often error-prone step in the arch-testing process.
Ask in #gentoo-dev or on the gentoo-dev mailing list if you need help.
</p>
<p>
<c>NATTkA</c> will set the <c>sanity-check</c> field on Bugzilla to either
<c>-</c> or <c>+</c> depending on whether the package list results in a
consistent dependency graph. You may need to add more packages or adjust the
arches listed for each package based on the output the bot posts as a comment
on the bug. Please note that arch teams may not process or notice bugs with a
blank or <c>-</c> sanity-check, so please fix this if it occurs <d/> or ask for
help to do so.
</p>
<note>
In addition, if you are changing the package list of a bug after it has been
processed, <d/> i.e. after NATTkA has CCed arches <d/> you should un-CC all
arches so that NATTkA CCs the new correct set of arches.
</note>
<note>
Note that sometimes NATTkA may do <e>nothing</e> if it has concluded the package
list is complete. You may wish to run <c>nattka sanity-check BUG</c> where
<c>BUG</c> is the bug number you're having an issue with in order to debug the
issue to receive verbose output.
</note>
<p>
You may wish to read NATTkA's
<uri link="https://github.com/mgorny/nattka#filing-keywordingstabilization-bugs">
documentation</uri> for help on package list syntax or other information about
the tool. The documentation details syntax which can be used, such as <c>*</c>
to represent "all previously stable arches", or <c>^</c> to copy the arches
from the line(s) above.
</p>
<p>
For an ebuild to move to stable, the following guidelines must be met
(see <uri link="https://www.gentoo.org/glep/glep-0040.html">GLEP 40</uri>
for further details):
</p>
<ul>
<li>
The ebuild has spent a reasonable amount of time in <c>~arch</c> first.
Thirty days is the usual figure, although this is clearly only a guideline.
For critical packages, a much longer duration is expected. For small
packages that have only minor changes between versions, a shorter period is
sometimes appropriate.
</li>
<li>
The ebuild must not have any non-<c>arch</c> dependencies.
</li>
<li>
The package version (and the ebuild) must not have any severe outstanding
bugs or issues.
</li>
<li>
The package version must be widely tested.
</li>
<li>
If the package is a library, it should be known not to break any package
which depends upon it.
</li>
</ul>
<p>
For security fixes, the "reasonable amount of time" guideline may be relaxed.
See the <uri link="https://www.gentoo.org/support/security/vulnerability-treatment-policy.html">
Vulnerability Treatment Policy</uri>.
</p>
</body>
<subsection>
<title>Stabilization rules</title>
<body>
<ul>
<li>
<c>amd64</c>, <c>x86</c>: If you are the maintainer of a package and own
the respective <c>amd64</c> or <c>x86</c> hardware, you can do your own
testing (stabilization and keywording) of your packages; as long as it is
not a core system set dependency. Note that it is acceptable to test
<c>x86</c> using a
<uri link="https://wiki.gentoo.org/wiki/Project:AMD64/32-bit_Chroot_Guide">
specialized environment</uri> on <c>amd64</c>.
</li>
<li>
<c>arm</c>, <c>arm64</c>: These teams have a strict policy on passing
testsuites. You <b>must</b> run test suites for packages with e.g.
<c>FEATURES=test</c> for Portage. Keywording or stabilizing packages which
fail these tests is avoided but acceptable if the test suite is fragile or
failures are known and reported. It is preferred to have to keyword or
stabilize more packages on these arches if needed for e.g. test dependencies
rather than masking or disabling tests here.
</li>
<li>
<c>sparc</c>: You must have prior permission from the arch lead. Usually we
expect you to be on the sparc alias for QA reasons, although other
arrangements can be made if you will only be working with a small group of
packages.
</li>
<li>
<c>alpha</c>: Maintainers may keyword their own packages but are reminded to
inform the Alpha team if they can help out with testing and keywording
packages so the team can keep an eye out for possible keywording mistakes.
</li>
</ul>
<p>
Exotic architectures (like <c>hppa</c>, <c>ia64</c>, <c>ppc*</c>, <c>sparc</c>)
are short on help, so it's best if you avoid opening bugs for stabilization
of new packages for them, unless it is absolutely necessary (e.g., a reverse
dependency for your package).
</p>
<p>
Some architectures (like <c>mips</c>, <c>riscv</c>) do not maintain a stable
keyword, so packages are not to be marked stable for one of these architectures.
</p>
</body>
</subsection>
<subsection>
<title>Simultaneous stabilization on all architectures</title>
<body>
<p>
If you maintain an architecture-independent package (data files, icons, pure
Python, ...), then you may request that your package be stabilized on all arches
at once. To do this <d/> when you are filing the stabilization bug <d/> please
add the keyword <c>ALLARCHES</c> and CC the arches that you would like to
stabilize.
</p>
<p>
If your package is architecture-independent, you should add the
<c><stabilize-allarches/></c> tag to metadata.xml. This allows consistency
in future stabilizations and saves arch teams considerable work.
</p>
<p>
The arch teams, when encountering the <c>ALLARCHES</c> keyword, should perform
their usual set of tests on a single convenient architecture. Then, if
everything works, stabilize not only the arch that was used during testing,
but also all of the other arches in CC on the bug. Afterwards, the CC field can
be cleared and the bug closed if appropriate.
</p>
<p>
Note that first-time <c>ALLARCHES</c> stabilizations are done "as normal" <d/>
i.e. all arch teams test individually as if it was not set. This nuance in the
procedure is part of why developers should not manually set <c>ALLARCHES</c> in
bugs, but instead let <c>NATTkA</c> set it automatically based on metadata.xml.
</p>
</body>
</subsection>
</section>
<section>
<title>Removing Package Versions</title>
<body>
<p>
When removing ebuild, ensure that you do not remove the most recent version at
any given keyword level on any profile. The aim here is:
</p>
<ul>
<li>
Never to force a downgrade. (Exception: occasionally you really do want to
force a downgrade, for example if the newly committed <c>foo-1.3</c> turns
out to be badly broken and that making everyone downgrade to <c>foo-1.2</c>
is the better option. This is rare.)
</li>
<li>
Do not break any existing dependencies.
</li>
</ul>
<p>
If you would like a particular package version moved to stable on certain arches
so that you can tidy up, file a bug.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb