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>
