keywording: it's preferred to rekeyword packages with new deps

It's preferred to rekeyword packages with their new dependencies in the
same bug rather than using `package.use.mask` as this means the new
code path(s) using the new dependencies get tested rather than just
the new package/dependency in isolation.

Also, no tooling exists for arch testers to automatically remove
the relevant mask(s) once keywording is done, so often we end up
with stale unnecessary masks remaining in tree.

Signed-off-by: Sam James <sam@gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/270
Signed-off-by: Sam James <sam@gentoo.org>

1 files changed, 10 insertions, 0 deletions

diff --git a/keywording/text.xml b/keywording/text.xml
index f794722..baffaaa 100644
--- a/keywording/text.xml
+++ b/keywording/text.xml
@@ -239,6 +239,16 @@ with <c>repoman</c> or <c>pkgdev</c> <d/> instead please commit with
 git commit message.
 </p>
 
+<p>
+Note that it is preferred to drop keywords on the package and request
+rekeywording of it together with its new dependencies within the same bug to
+allow the new code path(s) in your package to be tested. This won't happen if
+the new dependency is requested for keywording by itself and
+<c>package.use.mask</c> is used to mask the relevant new USE flag: only the
+new package dependency will be tested by arch testers. Also, the mask has to be
+manually removed during the testing process, which is cumbersome.
+</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