commit: 15dee0505f502a5eb3a248257b61f02f3f30bee9 Author: Sam James <sam <AT> gentoo <DOT> org> AuthorDate: Tue Mar 15 19:01:59 2022 +0000 Commit: Sam James <sam <AT> gentoo <DOT> org> CommitDate: Wed Mar 16 14:51:48 2022 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=15dee050
profiles/package.mask: mention masking development versions Closes: https://bugs.gentoo.org/319927 Signed-off-by: Sam James <sam <AT> gentoo.org> profiles/package.mask/text.xml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/profiles/package.mask/text.xml b/profiles/package.mask/text.xml index dd37b9b..299d153 100644 --- a/profiles/package.mask/text.xml +++ b/profiles/package.mask/text.xml @@ -14,6 +14,25 @@ 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
