Skip to content

general-concepts/slotting: mention incompatible changes, informing users #387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gentoo-bot merged 3 commits into from
Feb 28, 2026
Merged

general-concepts/slotting: mention incompatible changes, informing users #387

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
09db1c5
general-concepts/slotting: mention incompatible changes, informing users
thesamesam Feb 28, 2026
acd7e25
general-concepts/slotting: add 'Separate packages' subsection
thesamesam Feb 28, 2026
4af885f
general-concepts/slotting: mention autoconf program transformation op…
thesamesam Feb 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions general-concepts/slotting/text.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,12 +159,68 @@ of user scripts or tools, and build systems which expect the generic name
to be available.
</p>

<p>
For autotools-based packages, the <c>--program-prefix</c>,
<c>--program-suffix</c>, and <c>--program-transform-name</c>
<uri link="https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/html_node/Transformation-Options.html">
options</uri> options may be helpful.
</p>

<p>
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
<uri link="::general-concepts/news/">news item</uri>
or
<uri link="::ebuild-writing/messages/">ewarn</uri>
may be appropriate.
</p>

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

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

<p>
An <c>eselect</c> module is often made available for these cases, though
ebuilds normally shouldn't depend on its use.
</p>
</body>
</subsection>

<subsection>
<title>Separate package</title>
<body>

<p>
If a prospective newly-added slot would have a
<uri link="::general-concepts/dependencies/#blockers">blocker</uri>
(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.
</p>

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

<p>
An advantage of a separate package is that maintainers won't be tempted
(or prompted by <c>pkgcheck</c>) 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.
</p>
</body>
</subsection>
</section>

<section>
Expand Down