From 15dee0505f502a5eb3a248257b61f02f3f30bee9 Mon Sep 17 00:00:00 2001
From: Sam James <sam@gentoo.org>
Date: Tue, 15 Mar 2022 19:01:59 +0000
Subject: profiles/package.mask: mention masking development versions

Closes: https://bugs.gentoo.org/319927
Signed-off-by: Sam James <sam@gentoo.org>
---
 profiles/package.mask/text.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

(limited to 'profiles')

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
-- 
cgit v1.2.3-65-gdbad