[gentoo-dev] [PATCH] 2022-12-24-alternatives-introduction: add news item

[Sam James]

Bug: https://bugs.gentoo.org/886247
Bug: https://bugs.gentoo.org/886017
Signed-off-by: Sam James <sam@g.o>
---
 ...022-12-24-alternatives-introduction.en.txt | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 2022-12-24-alternatives-introduction/2022-12-24-alternatives-introduction.en.txt

diff --git a/2022-12-24-alternatives-introduction/2022-12-24-alternatives-introduction.en.txt b/2022-12-24-alternatives-introduction/2022-12-24-alternatives-introduction.en.txt
new file mode 100644
index 0000000..841e07a
--- /dev/null
+++ b/2022-12-24-alternatives-introduction/2022-12-24-alternatives-introduction.en.txt
@@ -0,0 +1,92 @@
+Title: Introduction of app-alternatives ebuilds
+Author: Sam James <sam@g.o>
+Posted: 2022-12-24
+Revision: 1
+News-Item-Format: 2.0
+
+Gentoo is introducing a new category of ebuilds called 'app-alternatives'
+to handle cases where a symlink for a common binary may want to be switched
+between different packages by a user.
+
+Traditionally, eselect was used for this, and while eselect still has its
+place, it's unsuitable for cases like /bin/awk and /bin/sh because it
+prevents immutable system directories and (more importantly
+from a package management perspective) relies on orphaned symlinks which
+means no package owns /bin/awk, /bin/sh, etc. This is not reliable and
+can lead to dead symlinks (or no symlink at all) in some edge cases [0].
+
+Systems will be more robust and desired system configuration
+can be achieved using the package manager rather than manual steps outside of it.
+
+The initial list of packages which support alternatives is as follows:
+- app-alternatives/awk
+- app-alternatives/bzip2
+- app-alternatives/bc
+- app-alternatives/cpio
+- app-alternatives/gzip
+- app-alternatives/lex
+- app-alternatives/sh
+- app-alternatives/tar
+- app-alternatives/yacc
+
+The stabilization of these new ebuilds and packages depending
+on them is ongoing in bug 886017 [1].
+
+## Per-upgrade requirements
+
+The default configuration on Gentoo systems is FEATURES="protect-owned"
+which works similarly to FEATURES="collision-protect" but it allows
+collisions between orphaned files. In this case, a one-off collision
+occurs as the app-alternatives/ ebuilds begin to claim once-orphaned
+symlinks.
+
+A similar issue occurred during the libxcrypt migration where users
+had upgrades interrupted by using the older, more aggressive
+FEATURES="collision-protect".
+
+It is recommended that users alter their configuration to
+remove references to 'collision-protect' in FEATURES and instead either
+explicitly enable 'protect-owned' in FEATURES or rely on the default
+(equivalent). It is also acceptable to simply disable collision-protect
+temporarily for the purposes of this news item.
+
+WARNING: Users with collision-protect enabled must disable FEATURES="collision-protect"
+in /etc/portage/make.conf by removing it or setting FEATURES="-collision-protect"
+if they have enabled it. collision-protect detects collisions between files including
+orphaned files where no package owns the file.
+
+## Migrating
+
+To migrate your system, a standard world upgrade will suffice:
+1. # emerge --sync
+2. # emerge -a -uvDU @world (or other similar standard world upgrade command)
+
+## Configuration
+
+Users who are not interested in using different implementations for
+various tools listed above can ignore this section.
+
+No configuration should be required by default, but users may wish
+to configure the new app-alternatives/ ebuilds to their tastes as they
+used to do via e.g. eselect-sh and eselect-awk.
+
+Going forward, /etc/portage/package.use will be used for this purpose.
+
+Users should review the USE flags available for the various app-alternatives
+ebuilds like app-alternatives/sh and adjust their configuration as desired.
+
+For example, to have /usr/bin/gzip be provided by app-arch/pigz for automatic
+parallelization of 'gzip', one would have the following in /etc/portage/package.use:
+```
+# https://wiki.gentoo.org/wiki/Gzip#Parallelization
+# Make /usr/bin/gzip be a symlink to pigz for a speedup in compression
+app-alternatives/gzip -reference pigz
+```
+
+## Further reading
+
+For more details, please see the technical documentation on the wiki [2].
+
+[0] https://wiki.gentoo.org/wiki/Project:Base/Alternatives#Why.3F
+[1] https://bugs.gentoo.org/886017
+[2] https://wiki.gentoo.org/wiki/Project:Base/Alternatives
-- 
2.39.0