From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: keywording/
Date: Wed, 30 Jul 2025 07:59:53 +0000 (UTC) [thread overview]
Message-ID: <1753862368.6f559e66bd979411a2580b0c6fa677d75eed69ae.ulm@gentoo> (raw)
commit: 6f559e66bd979411a2580b0c6fa677d75eed69ae
Author: Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
AuthorDate: Fri Jul 25 15:28:57 2025 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jul 30 07:59:28 2025 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6f559e66
keywording: Explain how stabilization groups work
Add explanation of stabilization groups to the devmanual, based on how
"pkgdev bugs" works, and the conversation in gentoo-dev ML [1].
[1] https://public-inbox.gentoo.org/gentoo-dev/49ec2455-9055-c9f7-9619-723f0d2a7ebf <AT> gentoo.org/
Signed-off-by: Arthur Zamarin <arthurzam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
keywording/text.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
diff --git a/keywording/text.xml b/keywording/text.xml
index 220447b..9288197 100644
--- a/keywording/text.xml
+++ b/keywording/text.xml
@@ -429,6 +429,54 @@ stable for one of these architectures.
</body>
</subsection>
+<subsection>
+<title>Stabilization groups</title>
+<body>
+
+<p>
+Stabilization groups are sets of packages defined to help organize and automate
+stabilization requests. These groups are stored under
+<c>metadata/stabilization-groups/</c>, and all files within this directory
+(including subdirectories) are included recursively.
+</p>
+
+<p>
+The main purpose of stabilization groups is to ensure that all packages in the
+same group are handled together in a single stabilization bug. This allows
+them to be stabilized in an "atomic" way: either all packages in the group are
+moved to stable together, or none are. This is especially useful for tightly
+related packages that must be kept in sync.
+</p>
+
+<p>
+Each group is named after to its path, with the ".group" filename suffix
+dropped. For example, a file <c>gnome/vte.group</c> defines the group
+<c>@gnome/vte</c>. This naming convention helps avoid collisions and makes
+referencing groups straightforward. The files use a simple format: one
+<c>cat/pkg</c> per line, with lines starting with <c>#</c> treated as comments.
+Whitespace before and after entries is ignored.
+</p>
+
+<p>
+When invoking tools like <c>pkgdev bugs</c>, passing a set (anything starting
+with <c>@</c>) will expand it to all packages listed in that set. For example,
+<c>@gnome/vala</c> would expand to <c>dev-libs/vala-common</c> and
+<c>dev-lang/vala</c>.
+</p>
+
+<p>
+During bug creation, packages whose latest matching version is already
+stabilized are dropped from the list. The tool then builds the full dependency
+graph as usual, adding any additional required packages. For each defined set,
+all packages included in both the graph and the set are merged into a single
+bug. For example, if <c>@gnome/vala</c> contains <c>dev-libs/vala-common</c> and
+<c>dev-lang/vala</c>, and both are required, they will be grouped into one bug.
+Packages in the set that are not required or requested are not included.
+</p>
+
+</body>
+</subsection>
+
<subsection>
<title>Keeping track of pending stabilizations</title>
<body>
next reply other threads:[~2025-07-30 7:59 UTC|newest]
Thread overview: 40+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-30 7:59 Ulrich Müller [this message]
-- strict thread matches above, loose matches on Subject: below --
2025-07-30 7:59 [gentoo-commits] proj/devmanual:master commit in: keywording/ Ulrich Müller
2025-07-30 7:59 Ulrich Müller
2022-03-16 14:52 Sam James
2022-03-14 17:07 Matt Turner
2022-03-10 23:33 Sam James
2022-02-18 18:19 Sam James
2022-01-22 21:35 Sam James
2022-01-22 21:35 Sam James
2022-01-22 21:35 Sam James
2021-10-13 13:42 Ulrich Müller
2021-10-13 13:42 Ulrich Müller
2021-07-16 9:11 Ulrich Müller
2021-07-03 16:21 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-04-07 17:35 Ulrich Müller
2021-03-30 16:10 Ulrich Müller
2021-03-11 13:16 Ulrich Müller
2021-02-17 9:29 Ulrich Müller
2021-02-17 9:29 Ulrich Müller
2021-02-17 9:29 Ulrich Müller
2021-02-17 9:29 Ulrich Müller
2021-02-15 7:21 Ulrich Müller
2020-07-12 18:32 Ulrich Müller
2020-05-06 7:49 Ulrich Müller
2020-01-25 6:02 Ulrich Müller
2020-01-23 13:50 Ulrich Müller
2018-08-27 15:24 Göktürk Yüksek
2015-06-17 12:05 Ulrich Müller
2015-03-14 9:20 Markos Chandras
2013-02-16 0:03 Markos Chandras
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1753862368.6f559e66bd979411a2580b0c6fa677d75eed69ae.ulm@gentoo \
--to=ulm@gentoo.org \
--cc=gentoo-commits@lists.gentoo.org \
--cc=gentoo-dev@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox