From 09db1c5df37cfab3f01aaf701a4fbdfc1af46c55 Mon Sep 17 00:00:00 2001 From: Sam James Date: Sat, 28 Feb 2026 13:52:36 +0000 Subject: [PATCH 1/3] general-concepts/slotting: mention incompatible changes, informing users app-containers/docker-compose is perhaps a good example of this. Bug: https://bugs.gentoo.org/835431 Signed-off-by: Sam James --- general-concepts/slotting/text.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index 767238ad..2b0be0bf 100644 --- a/general-concepts/slotting/text.xml +++ b/general-concepts/slotting/text.xml @@ -159,6 +159,16 @@ of user scripts or tools, and build systems which expect the generic name to be available.

+

+New slots are usually incompatible with older versions in some regard like +UI, syntax, behaviour. A new version of a slotted executable could suddenly +break users' workflows, so a +news item +or +ewarn +may be appropriate. +

+

An eselect module is often made available for these cases, though ebuilds normally shouldn't depend on its use. From acd7e250802fd31f52da0294b1c70260acde69d4 Mon Sep 17 00:00:00 2001 From: Sam James Date: Sat, 28 Feb 2026 13:58:08 +0000 Subject: [PATCH 2/3] general-concepts/slotting: add 'Separate packages' subsection Bug: https://bugs.gentoo.org/917327 Signed-off-by: Sam James --- general-concepts/slotting/text.xml | 39 ++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index 2b0be0bf..e2816515 100644 --- a/general-concepts/slotting/text.xml +++ b/general-concepts/slotting/text.xml @@ -169,12 +169,51 @@ or may be appropriate.

+

+Depending on the level of incompatibility, a separate package may be +more appropriate to avoid breaking scripts, cronjobs, and so on. +

+ +

+For example, app-containers/docker-compose in SLOT="0" installed a +standalone executable, while SLOT="2" installed a helper outside of +PATH which is no longer accessible to scripts. A separate package +may be more appropriate for such a case. +

+

An eselect module is often made available for these cases, though ebuilds normally shouldn't depend on its use.

+ + +Separate package + + +

+If a prospective newly-added slot would have a +blocker +(possibly because of file collisions) on another slot, using the same slot +or creating a new package may be more suitable instead. Users generally +expect slots to imply each can be installed in parallel. +

+ +

+Such new packages are usually in the same category and have the same +package name but with a number or other suffix. +

+ +

+An advantage of a separate package is that maintainers won't be tempted +(or prompted by pkgcheck) to clean up old versions which are shadowed +by newer ebuilds. A similar concern exists for stabilization where tooling +will prompt developers to stabilize a new version when both the old and new +versions may be intended to co-exist indefinitely. +

+ +
From 4af885ffa42eed302b5d4b15254406a0361af072 Mon Sep 17 00:00:00 2001 From: Sam James Date: Sat, 28 Feb 2026 14:05:56 +0000 Subject: [PATCH 3/3] general-concepts/slotting: mention autoconf program transformation options Signed-off-by: Sam James --- general-concepts/slotting/text.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index e2816515..c3d8e96f 100644 --- a/general-concepts/slotting/text.xml +++ b/general-concepts/slotting/text.xml @@ -159,6 +159,13 @@ of user scripts or tools, and build systems which expect the generic name to be available.

+

+For autotools-based packages, the --program-prefix, +--program-suffix, and --program-transform-name + +options options may be helpful. +

+

New slots are usually incompatible with older versions in some regard like UI, syntax, behaviour. A new version of a slotted executable could suddenly