Gentoo Stability Indicators- what do keywords mean?

I’m not a core Gentoo dev, but this is my understanding of what the stability indicators mean, having used Gentoo for about a year now.

There’s three levels of stability, indicated by whats called a “keyword”:

The stability of a package is both per-version, and per-architecture. So a package version with keywords “amd64 ~arm64” is:

So what do these three things actually mean? Let’s go from least to most stable.

Unkeyworded

A package is unkeyworded when the package maintainer does not know if it will even build and install correctly, let alone run. All packages start out unkeyworded on new CPU architectures, since no one knows initially what will and won’t work on it.

Some packages have build scripts that always build the latest bleeding-edge version of the source code, usually marked with a 9999 or 99999999 version number. These packages are always unkeyworded, since the package will always download the latest source code when you run the build for it, and the maintainer has no way to guarantee that will actually work.

To install an unkeyworded package, you have to add it to /etc/portage/package.accept_keywords

Usually this looks something like:

<sys-libs/freeipmi-9999 **

This ** wildcard will allow you to install the package even if there are no keywords for your architecture. The < and -9999 excludes any bleeding-edge live build versions. You don’t need to include it if the package has no bleeding-edge build script, but I like to include it regardless in case it gets one later.

Unstable

A package is unstable on a given CPU architecture when it is known to build on that architecture, and maybe known to work in some capacity, but has not been thoroughly tested. Package maintainers might mark a package as unstable themselves. As a user, you can also file a request for a package to be marked as unstable, telling them that you have built the package on the architecture and it seems to work for you. The wiki has instructions (wiki/Knowledge Base: Missing keywords and keyworq requests) for how do to this. You should probably make sure all its dependencies are keyworded first.

Generally speaking, you shouldn’t submit a request to keyword a version unless other archictectures already have at least on unstable keyword for that version. If none of them have a keyword, the maintainer probably does not consider that version to be keyword-worthy in general.

I think that once a package is keyworded on an arch, it stays that way for new versions unless someone comes in to say that it is now thoroughly broken on the arch and needs to be unkeyworded. That means that just because something is unstable, does not mean it will actually build/work correctly. But it does mean it at least used to, so fixing it may not be too bad if there is trouble.

To install an unstable package, you can again add it to /etc/portage/package.accept_keywords, but this time you add it as something like:

dev-lua/luaposix ~arm64

A tilde in front of your CPU architecture. You can also globally accept unstable for all packages, but I do not do this. It can be frustrating to reverse this change if you do this and decide it is not for you.

Stable

A package version is stable on a given CPU architecture when it is known to build, run, and generally work as it is supposed to. It’s not an indication that the software has no bugs- all software has bugs. But it’s an indication that it’s considered about as good as it will get for general use.

Stabilization has a more involved set of requirements, but like unstable, you can request a package be marked stable as a user. See the wiki/Stable request. Stabilizing a package has a much higher cost on a package maintainer than unstable-keywording it, so maintainers will only do it within the bounds of what they have energy to commit towards it, and will prioritize packages they think have the most users.

What to expect out of different CPU architectures

On amd64 (x86_64), the vast majority of stuff is marked stable. It is where the most maintainer time goes. You will still need to accept some unstable software, but unkeyworded software is rare.

On arm64 (aarch64), you will have a pleasant amount of stabilized software available, but you will frequently need to accept unstable versions of software, and you will need to accept unkeyworded software with some regularity (go make keyword requests! This is an instruction for me too, I have been putting it off).

Straying from there into architectures like ppc64 or riscv you will find progressively fewer keywords and stable software. Such is life on these architectures.

GURU is different

Packages in GURU, the Gentoo user repository, will never be stable. It’s not allowed. Additionally, keywording happens not by filing an issue but by just comitting the keyword as a change to the repo. If you want to keyword a package, message the package maintainer or become a contributor yourself and commit the keyword.

As a contributor, I don’t commit keywords unless I’ve actually tested the build myself and am pretty sure it will work.