profiles/package.mask/text.xml


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

<?xml version="1.0" encoding="UTF-8"?>
<guide self="profiles/package.mask/">
<chapter>
<title>Profiles <c>package.mask</c> file</title>
<body>

<p>
The <c>package.mask</c> file can be used to hard mask packages or
certain versions of packages that should not be merged by users.
This is often used when adding certain experimental (either in ebuild
or upstream terms) packages to the tree, or to prevent merging of
packages that are broken or break something else. Every entry should
have a comment detailing the specific reason for the mask. The format
of the <c>package.mask</c> file is described in <c>man portage</c>.
</p>

<p>
Development or unstable (per upstream declaration/categorization) versions of
packages should usually be masked in <c>package.mask</c>. Upstreams may not
deem such releases to be ready for general distribution (or safe to use), or
may not be expecting bug reports from the wider userbase yet. The default
should generally be to mask such versions, but it is acceptable to not mask
in some circumstances <d/> e.g. upstream make very infrequent releases, the
changes are safe (reviewed by the Gentoo maintainer), or perhaps other
distributions are shipping the same new version. As an alternative to a
development version, you may also consider backporting required upstream fixes
to the released version.
</p>

<p>
Overall, masking something and unmasking if it turns out to be stable is
safer (and leads to a better user experience) than the inverse (pushing
unmasked and breakage occurring).
</p>

<p>
Entries are added chronologically <d/> that is, newer entries
should be placed towards the top of the file, underneath any initial
header comment block.
</p>

<p>
This file can be used in subprofiles to mask packages only for certain setups.
</p>

</body>
</chapter>
</guide>