+ + + + + + +

Gentoo Policy Guide¶

Gentoo Policy Guide aims to become a definitive clear source of all +Tree Policies that are currently binding to Gentoo developers. +It combines both policies that are global by design (i.e. set by the QA +team or the Council), as well as specific to other Gentoo projects. +The policies are meant to be supplied with rationale and clear +indication of the body setting the policy, and therefore the process +in which the policy can be updated.

Preface¶

Introduction¶

Authors¶

This document is maintained by the Gentoo QA project.

The current text authors are:

Michał Górny (mgorny)

License¶

This work is licensed under the Creative Commons Attribution-ShareAlike +4.0 International License.

Motivation and history¶

Historical state of policy documentation¶

At the time, Gentoo was lacking a clear and focused document listing all +development-related policies in a concise and clear way.

PMS provided a technical specification for the ebuild files but did +not provide a sufficient explanation on how to use it. Furthermore, PMS +was focused on wider usage of the ebuild files than intended for +the Gentoo repository, and therefore was partially restricted via tree +policies.

Past Council decisions can be found in the Council meeting logs. +However, their form makes it hard to find any particular decision, +not to mention establishing a complete list of policies.

At some point, the QA team started listing QA policies on its wiki +page. Only eight policies were listed so far. The policies were written +out as a flat list with no particular order which is not going to scale +well.

Finally, there was an attempt to turn devmanual into a source of +reference policies. It was rejected by its maintainers as explicitly +against the original purpose of this document. Furthermore, a large +amount of stale information combined with ability to edit by every +developer would make it unclear which parts are applicable policies, +and which are obsolete or non-binding tips.

There are also project policies, scattered across wiki pages and other +project documentation, and a lot of de facto policies that were +established less or more formally in the past but were never really +written down.

Purpose of the Policy Guide¶

The Policy Guide was created in order to address aforementioned +documentation deficiencies. Its primary purpose is to collect all +applicable policies from various sources and combine them into a single +logically organized document.

Along with a wording of each policy, its rationale should be provided +(if available) and an indication of which body set the policy. +The former should make it possible to better understand the policy, +and apply it in spirit rather than requiring very precise wording. +The latter should make it clear who can be queried for additional +information, and how the policy can be updated if need arises.

This Guide is going to replace the QA team policies page. All new QA +policies will be documented directly in it. Other documentation (e.g. +devmanual) should conform to policies stated here.

Basic information¶

Goals of policy making¶

The Gentoo policies focus on three aims:

Portability. By following the policies, it should be possible +to package software so that it works on different system setups. +This includes various supported architectures, basic system +components, service managers, package managers, combinations +of compiler and linker flags, etc.
Maintainability. The policies aim to provide consistent coding +practices that make it easy for a different person to co-maintain +the package or take over after previous maintainer. This also +reduces the risk of mistakes experienced by the end users.
End-user experience. The policies try to help developers +in providing a consistent end-user experience. The same concepts +applied across different packages make it easier for user to achieve +his goals and reduce the likeliness of surprising behavior.

Policy compliance checking¶

Currently, there are two kinds of tools involved in detecting policy +violations:

Linting-class tools, including repoman and pkgcheck. Those tools +analyze ebuilds and other files in the package repository for known +policy violations. They are limited to checking for problems that +can be detected without running the phase functions.
Build- and install-time QA checks, implemented in package managers. +Those trigger while the ebuilds are executing. They are limited +to testing the currently running code path.

Developers are expected to use both kinds of tools before pushing their +commits. They should both lint the changed ebuilds using repoman +or pkgcheck, and test whether their packages build and install +correctly.

Additionally, Gentoo is running pkgcheck periodically as Gentoo CI. +All non-trivial violations are reported to the gentoo-automated-testing +mailing list and to the developers making the relevant commits. This +supplements the direct use of linting tools by developers with reliable +tree-wide scans.

Policy enforcement¶

The Gentoo QA team is tasked with enforcement of the tree policies. +Its role is governed by GLEP 48. It focuses on documenting +the policies, resolving doubts regarding them and educating +the developers.

The QA team members can also take direct action in resolving minor +quality problems (i.e. when fixing directly involves far less effort +than if the developer was requested to fix it), or when developer +refuses to resolve policy violations.

Finally, in case of repeated unwillingness to follow policies, the QA +team can issue disciplinary measures against the developer in question.

Policy making, changes and appeals¶

The majority of policies are written down and maintained by the QA +team. Other Gentoo projects also create policies that affect their +specific areas of contributions (e.g. systemd project created +policies related to installing systemd unit files).

Each policy listed in this document indicates the body maintaining it. +In order to change or abolish the policy, that team should be contacted. +If the project in question disagrees with the change, QA team can be +asked to override the policy. All QA decisions and policies can further +be appealed to the Council.

Dependencies¶

Optional runtime dependencies¶

PG: 0001
+
Source: QA
+
Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS
+
Reported: no
+

Using USE flags to control optional runtime dependencies is not +acceptable except under very specific circumstances, such as a package +being nonfunctional unless at least one of a set of optional runtime +dependencies is installed.

There is no specific preference as to how user should be informed +of optional runtime dependencies. Three possible ways are +optfeature from eutils eclass, readme.gentoo-r1 eclass +and plain elog messages.

Rationale: toggling USE flags in order to enable or disable optional +runtime dependencies causes needless rebuilds of packages in question. +This is especially important for packages that take long time to build.

Note

GLEP 62 proposes a solution permitting flipping USE flags without +rebuilding package in question. It has been tentatively approved +by the Council but no reference implementation has been written.

=-dependencies with no revision¶

PG: 0002
+
Source: QA
+
Reported: by repoman and pkgcheck
+

Whenever a non-wildcard = (equals) dependency is used on a package, +the requested revision must be specified explicitly. When the zeroth +revision is requested, -r0 must be used. When no specific revision +is necessary, the ~ (tilde) operator must be used instead.

Example:

# BAD:
+=dev-libs/libfrobnicate-1.2.3
+# GOOD:
+=dev-libs/libfrobnicate-1.2.3-r0
+=dev-libs/libfrobnicate-1.2.3-r3
+~dev-libs/libfrobnicate-1.2.3
+

+

Rationale: using = operator in place of ~ to mean a specific +version has been a common mistake. This policy uses the fact that +no revision and explicit -r0 are equivalent. By explicitly +requesting the latter, it warns developers to reconsider whether they +used the correct operator.

Slot and subslot dependencies¶

on (sub-)slotted packages¶

PG: 0011
+
Source: QA
+
Reference: https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f
+
Reported: by repoman and pkgcheck
+

Whenever a package dependency specification matches a range of versions +that span different slots or subslots, the package must explicitly +include slot specification. If the := operator is not applicable +and any slot is acceptable, explicit :* operator must be used. +If the :<slot>= operator is not applicable and only a specific slot +can be used, :<slot> value must be explicitly specified.

Package dependency specification without explicit slot specifier can +be used on packages that are not slotted nor subslotted at the moment.

Rationale: this policy aims to help detecting missing slot operators +when dependencies start using slots or subslots. It uses the fact that +the explicit :* operator is equivalent to no slot specification, +and therefore can be used interchangeably. In this case, we assume +that the latter means ‘dependency not verified yet’, while the former +means ‘verified that any slot is acceptable’.

Note

The Paludis package manager applies different logic when no slot +is specified on the dependency. It pulls in the slot corresponding +to the newest package version available.

special case: Qt packages¶

PG: 0012
+
Source: Qt project
+
Reference: https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies
+
Reported: no
+

The Qt packages use subslots in an uncommon way. The public ABI of Qt +libraries is stable within each slot, and the subslot is used to refer +to private ABI. Therefore, the := operator must only be used +if your package uses one of the private API parts, and plain :5 +or likewise dependency must be used otherwise.

proactive use of slot operators¶

There is an open debate on whether developers should be proactively +adding := slot operators on packages that do not define subslots +yet.

Proponents of the idea point out that adding slot operators to reverse +dependencies after the package becomes slotted is cumbersome and usually +results in losing the subslot rebuild opportunity at least once. They +argue that in many cases the future use of subslots is reasonably +predictable.

Opponents claim that the future use of subslots is not 100% predictable. +They point out the case of Qt packages as an example.

Revision bumps on runtime dependency changes¶

PG: 0003
+
Source: Council
+
Reference: https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
+
Reported: no
+

It must not be assumed that changes to package’s dependencies will +be implicitly propagated to users who have installed the package +already. Whenever the change needs to be propagated (e.g. to prevent +a missing runtime dependency from being cleaned), the package revision +must be increased.

This does not apply to build-time dependencies.

Rationale: developers were historically relying on Portage’s behavior +called dynamic dependencies which caused Portage to implicitly use +dependencies specified in matching ebuilds for installed packages. This +is non-portable and unreliable. Users using different package managers, +disabling the feature or simply missing the timeframe during which +the old ebuild version existed had experienced dependency graph breakage +and other problems due to it.

The policy requires developers to explicitly account for that +possibility. Revision bumps ensure that users who installed the package +from the previous ebuild version rebuild it and get the updated +dependencies as a result.

Note

The dynamic dependency usage problem has a flip side. You can’t rely +on in-place dependency changes not being propagated either. For +example, if you notice that a package linked to libfoo unnecessarily, +and decide to remove the dependency and code responsible for linking +to it in place, Portage may apply the former immediately even +if the package installed by the user still links to libfoo.

USE dependencies¶

on packages without the flag¶

PG: 0021
+
Source: QA (inferred from PMS)
+
Reported: by pkgcheck
+

Whenever a package uses a 2-style USE-dependency on another package, +all package versions matching the dependency must have the flag +in question. If the dependency matches at least one version missing +the flag, either 4-style USE-dependency (i.e. having (-) or (+) +indicator) must be used, or the restriction must be refined to match +only versions having the flag.

Example:

# BAD: USE=gtk2 is not supported by v2
+dev-foo/libfrobnicate[gtk2]
+# GOOD: all matching versions have USE=tools
+<dev-foo/libfrobnicate-2[gtk2]
+# GOOD: indicate the default
+dev-foo/libfrobnicate[gtk2(-)]
+
+# BAD: USE=tools is no longer needed with v2
+dev-foo/libbar[tools]
+# GOOD: indicate the default
+dev-foo/libbar[tools(+)]
+

+

Rationale: according to the PMS section on 2-style and 4-style USE +dependencies, it is an error to apply 2-style USE dependency to +a package missing the flag. Furthermore, checking for this makes it +possible to report whenever USE flags on a package are changed without +updating its reverse dependencies.

Ebuild file format¶

Coding style¶

PG: 0101
+
Source: QA
+
Reported: partially via repoman and pkgcheck
+

While Gentoo leaves most of the coding style choices to developers, +there are a few rules which we try to enforce. Those are:

Always indent using a single tab for indentation level. Do not +attempt to align, as it will not work with different tab widths.
Whenever using named variables, use bracketed variable form, i.e. +${foo} rather than $foo.
Use bash conditions [[ ... ]] rather than POSIX-ish [ ... ] +or test builtin.

Rationale: the recommended constructs are less error-prone. +Consistency avoids unnecessary changes when other developers edit +the ebuild.

Code must be contained within ebuild and eclasses¶

PG: 0102
+
Source: QA
+
Reference: https://bugs.gentoo.org/612630
+
Reported: no
+

The ebuild code must be fully contained within .ebuild and .eclass +files. It is forbidden to load additional ebuild code from other files +via source, eval or any other possible method.

This affects historical use of ‘eblits’ to include phase functions from +external files. The eblits used by the few affected packages were +converted into eclasses.

Rationale: moving ebuild code to non-standard locations is against +the principle of least surprise. It makes the maintenance harder, +confuses other developers and tools that do not explicitly account for +that possibility, including linting tools.

HOMEPAGE must not contain variables¶

PG: 0103
+
Source: QA
+
Reported: by pkgcheck, highlighted as error by gentoo-syntax
+

The HOMEPAGE variable in ebuild must specify all the URIs verbatim, +without referring to any variables. Variable references are allowed +when setting generic values in eclasses.

Rationale: since homepage URIs do not contain dynamic parts (such +as package versions), there is little advantage to using variables +there. On the other hand, variables render the URIs unusable without +preprocessing, breaking URI support in terminals and editors, as well +as reducing the usefulness of plain tools such as grep.

SRC_URI must not refer to HOMEPAGE¶

PG: 0104
+
Source: QA
+
Reported: by pkgcheck
+

The SRC_URI variable in ebuild must not refer to ${HOMEPAGE}. +If both overlap, the common part must be repeated verbatim.

Rationale: HOMEPAGE permits multiple entries by design, +and developers are generally encouraged to add more helpful entries +(e.g. project pages on PyPI, GitHub…). Making individual URIs +incidentally depend on multi-valued variable having a single value +goes against the principle of least surprise. Furthermore, it makes +it hard to copy-paste part of the URI e.g. to investigate the directory +index.

KEYWORDS must be defined on a single line¶

PG: 0105
+
Source: QA
+
Reported: no
+

The KEYWORDS variable must be defined at most once in an ebuild, +on a single line, with literal content (no variable references, line +wrapping, appending, etc.).

Rationale: it is common for arch teams to use the ekeyword tool +when working with large number of ebuilds. The tool has only limited +ability to process and modify ebuilds, and therefore developers must +make sure that it works correctly on their ebuilds.

File system layout¶

Installation paths¶

PG: 0201
+
Source: QA
+
Reference: https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths
+
Reported: via install-qa-check.d
+

Gentoo packages may only install into one of the following top-level +directories:

/bin
/boot

/dev
/etc

/lib*
/opt

/sbin
/srv

/usr
/var

Furthermore, only the following subdirectories of /usr are permitted:

/usr/bin
/usr/include

/usr/lib*
/usr/libexec

/usr/sbin
/usr/share

/usr/src
/usr/<triplet>

Furthermore, within /usr/share/doc hierarchy only a subdirectory named +after full package name and version with revision (PF) is permitted.

In the aforementioned lists, ‘lib*’ indicates lib and its appropriate +suffixed variants for the architecture in question. ‘<triplet>’ +indicates either CHOST or CTARGET value, as used by toolchain packages.

Additional exceptions can be granted by the QA team. Currently those +exceptions are:

/gnu for the guix package manager
/nix for the nix package manager

Support for separate /usr¶

PG: 0202
+
Source: QA
+
Reference: https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt +https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt
+
Reported: no
+

Developers are not required to support using separate /usr filesystem +without an initramfs.

Rationale: upstream software (as of 2013) is already making support +for early boot without /usr mounted difficult, and whenever it is still +works, it is either subtly broken or relying on hacks (udev). In setups +using initramfs, some of the boot and repair functionality can be moved +from rootfs to initramfs.

Strict multilib layout¶

PG: 0203
+
Source: QA
+
Reference: https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict
+
Reported: via install-qa-check.d, fatal
+

Libraries must be installed into an appropriate /lib* or /usr/lib* +directory corresponding to their ABI. For example, 64-bit libraries +on amd64 must be installed into lib64 and not lib.

Libraries installed as a part of larger software package can be +installed along with it into a subdirectory of lib.

Rationale: historically, Gentoo has been symlinking /lib to /lib64 +in order to maintain compatibility with old packages hardcoding /lib +path. With modern Gentoo profiles, this is no longer the case +and packages must install libraries into appropriate directory for them +to be correctly found by the dynamic loader.

Static libraries and libtool files¶

PG: 0204
+
Source: QA
+
Reference: https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries
+
Reported: via install-qa-check.d, fatal
+

Static libraries and libtool files (.la) must be installed into /usr +hierarchy and never to root filesystem (/lib*). If an additional shared +version of the library is installed to /lib*, a .so linker script must +be installed into /usr/lib* in order to ensure correct linking.

Rationale: historically, the purpose of root filesystem was to hold +files strictly needed at boot. For this reason, many old Gentoo +installations may still use small / partition. Static libraries are +used only during package builds, and installing them to rootfs would +be a waste of space.

Game install locations and ownership¶

PG: 0205
+
Source: Council, clarified by QA
+
Reference: https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt +https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
+
Reported: via install-qa-check.d
+

The historical game install locations (/usr/games and /etc/games) must +not be used anymore. Instead, games should follow normal guidelines +for install locations. As an exception, /usr/share/games can be used +if this location is used upstream, and /var/games can be used for shared +game files (e.g. high scores, game state files).

The historical games group must no longer be used. Games must work +for users that are not in this group. The aforementioned install +locations must therefore be owned by root and be world-readable.

If games need privileged access to shared files, the group gamestat +can be used for this purpose. The game executables should be owned +by that group and made setgid. The shared files must be installed +into /var/games hierarchy, and writable to gamestat group.

Rationale: there is no technical reason to isolate games from other +applications on the system, or to restrict access to them. The boundary +between game and non-game packages is very blurry on modern systems, +especially due to web browsers.

The historical use of games group on Gentoo to control access is +inconsistent with the use in other distributions where it was used to +share data files. Since the latter implied users must not be added +to the games group, a new group (gamestat) needed to be created to +fulfill that purpose.

Absolute symbolic link targets¶

PG: 0206
+
Source: QA
+
Reported: by repoman and pkgcheck (when ebuild-generated)
+

Packages must not install symbolic links with absolute targets. +Instead, relative paths must be used. An exception is granted +for symlinks to specially mounted filesystems (such as /proc, /run) +when symlinks are supposed to always reference the running host system.

Example:

# BAD:
+dosym /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate
+# GOOD:
+dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate
+# ACCEPTABLE EXCEPTION:
+dosym /proc/self/mounts /etc/mtab
+

+

Rationale: absolute symlinks work correctly only when the root +filesystem is mounted at /. They point at the wrong location whenever +it is mounted in another location, e.g. for the purposes of recovery.

Installed files¶

Installation of small files¶

PG: 0301
+
Source: QA
+
Reported: no
+

Ebuilds must not introduce USE flags to control installing files that +are small in size, require no additional dependencies and not cause any +negative consequences to the program behavior by being installed. Such +files must be installed unconditionally. Examples include shell +completion files, systemd service units, localization files.

Users wishing to strip unnecessary files of this category should use +INSTALL_MASK to do so.

Rationale: the goal of this policy is to avoid unnecessary rebuilds +of packages when the cost of installing additional files is much smaller +than the cost of rebuild. It has been specifically brought in context +of bash completions in LibreOffice – a user who did not notice that he +did not enable the flag should not be required to spend hours rebuilding +such a huge package in order to install one tiny file.

Note

While technically e.g. app-shells/bash-completion could be +considered a dependency of installed bash completions, it is not +applicable here since this package needs to be installed by the user +if he wishes to use completions in the first place, and if it is not +installed, completion files are not used at all.

Installation of static libraries¶

PG: 0302
+
Source: QA
+
Reported: no
+

Packages must not install static libraries unless they are explicitly +required, either by themselves or their reverse dependencies. If both +shared and static libraries are supported, shared libraries must be +installed by default and USE=static-libs may be added for static +libraries if they are necessary.

Rationale: static linking is strongly discouraged as it makes security +support for packages practically impossible. It may be used whenever +really necessary (e.g. for recovery tools) but otherwise proliferating +it is considered harmful. There is no point in installing static +libraries if they are never going to be used.

Installation of libtool (.la) files¶

PG: 0303
+
Source: QA
+
Reported: no
+

Packages must not install libtool .la files unless they are explicitly +required. Generally, they might be required if:

the package is using a plugin loader that requires .la files in order +to locate plugins and does not have .so fallback (very uncommon),
the package is installing static libraries that have additional +dependencies and no pkg-config files or other tools that provide +the list of dependencies to build systems.

It is recommended to use the following one-liner to remove .la files:

find "${ED}" -name '*.la' -remove || die
+

+

Rationale: libtool files were historically introduced as an attempt +to supplement static library archives with dependent library list. +However, they were only supported by libtool-based (autotools) projects +and caused many issues, in particular due to hardcoding full paths. +Today they are practically replaced by more portable pkg-config files, +and while libtool keeps generating them, they are considered +unnecessary and potentially harmful.

Keywording and stabilization¶

Rekeywording on dropped keywords¶

PG: 0401
+
Source: QA
+
Reported: by pkgcheck and repoman
+

The developer removing keywords from a package (e.g. due to new +dependencies) must file a rekeywording bug asking for the package being +retested. This rule can be exempted if the package is known not to work +(anymore) on the arch in question.

Rationale: rekeywording on minor architectures often takes a long +time. If a developer neglects to request it immediately, it negatively +affects other developers who in the future either want to stabilize +a new version or to remove an old version.

Stabilizing new versions¶

PG: 0402
+
Source: QA
+
Reported: by pkgcheck
+

Whenever requesting a stabilization of a new version of the package, +the developer must CC all arches that had at least one previous stable +version of the package in question, and that still have ~arch keywords +in the stabilized version. This applies to experimental architectures +as well.

The stabilization request can be closed and old stable version removed +once all non-experimental architectures have processed the stabilization +request. However, the remaining arch teams should be kept CC-ed in case +they wanted to process the bug.

Rationale: there were some cases of developers requesting +stabilization only of a subset of architectures they were personally +interested in. This meant some other developer had to independently +request stabilization on remaining architectures which only meant +a duplication of effort and unnecessary confusion over which version +is stable and whether arch teams are slacking or stabilization was not +requested on remaining architectures in the first place.

Removing stable keywords¶

PG: 0403
+
Source: QA
+
Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs
+
Reported: n/a
+

Stable keywords (or the last stable version) can be removed from +a package if the relevant arch team does not respond within 90 days. +If the removal causes a breakage of dependency graph, the developer +must work with maintainers of the depending packages before proceeding +with it.

The policy for removing a package must be followed here, with exception +of last rite mails.

Language-specific policies¶

Python¶

Eclass usage¶

PG: 0501
+
Source: Python project
+
Reference: https://wiki.gentoo.org/wiki/Project:Python/Eclasses
+
Reported: by pkgcheck
+

All packages using Python (either through installing Python modules +or scripts, linking to libpython, calling Python at runtime or build +time) must do it through one of the python-r1 eclasses. Packages must +not directly depend on Python, directly use PYTHON_SINGLE_TARGET +or PYTHON_TARGETS. The variables and functions provided by the eclasses +must be used instead.

All ebuilds must explicitly define supported Python implementations +in PYTHON_COMPAT. Dependencies between Python packages must use +PYTHON_USEDEP, PYTHON_SINGLE_USEDEP or python_gen_cond_dep in order +to ensure implementation match.

Rationale: the eclass code guarantees consistent and reliable handling +of slotted Python. It ensures that the whole dependency graph uses +matching implementation and that programs will not accidentally break +if user changes his Python preferences. The helper functions +and variables also make it possible to gracefully retire old +implementations with minimal changes to existing ebuilds.

Python 2 deprecation¶

PG: 0502
+
Source: Python project
+
Reference: https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life
+
Reported: no
+

Python 2 is being phased out of Gentoo packages. Python 2 support +must not be introduced in new packages, unless explicitly required +to maintain compatibility with existing packages. Packages that do not +support Python 3 should be removed sooner or later, depending +on Python 3 porting chances.

In packages that support both Python 2 and Python 3, the Python 2 +support should be gracefully retired, as soon as their reverse +dependencies are ready or removed.

Rationale: Python 2 has reached its (deferred) end-of-life by the end +of 2019. Many important upstream projects have already removed support +for Python 2. Those packages are frequently dependencies of other +packages, causing the cost of maintaining Python 2 support to grow +exponentially.

Early removal of unnecessary Python 2 support will both reduce +the long-term maintenance costs, and give users better chance to prepare +than delaying it until the number of packages losing Python 2 support +will cause major upgrade issues.

Package Maintainers¶

Adding new maintainers¶

PG: 0601
+
Source: QA
+
Reported: no
+

Developers must not add other developers as package maintainers, unless +the developers in question consent to that. Developers must not add +projects that they are not members of as package maintainers, unless +one of the project members explicitly agrees to that or the project +policy explicitly permits it.

Rationale: this policy aims to prevent package maintainers being added +as backup maintainers without their consent or knowledge. What’s worse, +once the original maintainer resigns the packages frequently drop +to backup maintainers who are neither interested in maintaining them, +nor often aware why they are listed as maintainers.

For example, developers used to frequently add Python team as a backup +maintainer to various packages not fitting the project’s profile. This +includes various end-user programs written in Python. Many of those +packages ended up being maintained solely by Python, and distinguishing +them from packages actually within project’s profile was hard.

New packages without a maintainer¶

PG: 0602
+
Source: QA
+
Reported: no
+

It is explicitly forbidden to add new packages without a dedicated +maintainer. This does not apply if the package in question is not +technically a new one but merely split out of unmaintained package.

Rationale: Gentoo is currently suffering from a very large number +of packages without a maintainer. There is a small group of developers +trying to fix them as necessary. It is unfair and inappropriate +to increase their maintenance burden by adding new packages and refusing +to take care of them.

Removing package maintainers¶

PG: 0603
+
Source: QA
+
Reported: no
+

When removing maintainers from a package, the developer must reassign +all bugs filed for it. Furthermore, when removing the last maintainer +for a package, the developer must add the following comment +to metadata.xml:

<!-- maintainer-needed -->
+

+

Furthermore, the developer must send an ‘up for grabs’ mail +to gentoo-dev mailing list, containing the list of packages with +no maintainer. If possible, please include any information that could +be helpful to future maintainers.

Rationale: reassigning bugs is necessary to make sure that old bugs +are not lost assigned to developers who are no longer interested +in them. The maintainer-needed comment is meant to make it possible +to easily grep for unmaintained packages. The ‘up for grabs’ mails aim +to increase the chances of packages finding a new maintainers (compared +to them silently becoming maintainer-needed).

Other metadata variables¶

Dynamic slots (multislot flag)¶

PG: 0701
+
Source: QA (inferred from PMS)
+
Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT
+
Reported: use in global scope triggers fatal error
+

The use of multislot to alter SLOT values (as well as any other +USE-dependent slot values) in the Gentoo repository is forbidden. +Such a feature can be used in overlays, and it is acceptable to provide +such support in eclasses as long as it is not used in ::gentoo.

This policy has been explicitly declared in response to historical +(pre-2016) use of USE=multislot in toolchain ebuilds. When the flag +was disabled, all package versions used the same slot, and upgrades were +handled as for non-slotted packages. When the flag was enabled, each +version used a separate slot, permitting multiple versions being +installed simultaneously. This allowed the user to choose between +the two options.

The original violation has been resolved by unconditionally slotting +the packages. This permitted the users to install multiple versions +in parallel, while removal of old versions was to be handled via +emerge --depclean.

Rationale: this feature was in direct violation of PMS metadata +invariance requirements. It caused the cached slot value to depend +on the state of querying the USE flag (which in turn could technically +depend on slot, via package.use). This caused undefined package +manager behavior which could include use of unpredictable slot, cache +invalidation or explicit errors.

HOMEPAGE value must be meaningful¶

PG: 0702
+
Source: QA
+
Reference: https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035
+
Reported: known bad values are reported by pkgcheck
+

The HOMEPAGE specified for the package should either be dedicated +to the package in question or make it easy to find dedicated +information. Packages must not use https://www.gentoo.org/ +or a similar generic homepage. If no homepage is available, the special +value of https://wiki.gentoo.org/wiki/No_homepage must be used.

Rationale: The homepage specified in ebuilds is normally used to +locate information about the upstream project, e.g. downloads, source +code repository, bug tracker, documentation. Homepages that make it +hard to locate information about a specific project have little value, +and the Gentoo homepage generally does not do a good job at linking even +major Gentoo projects. Furthermore, many of the projects did not even +have a single dedicated subpage anywhere in Gentoo web space. In all +those cases, using the explicit No_homepage marker at least makes it +easy to identify such packages.

RESTRICT=test for USE=-test¶

PG: 0703
+
Source: QA
+
Reported: by pkgcheck
+

Whenever the package uses test flag to control test prerequisites +(or another flag with a similar purpose), it must explicitly restrict +tests when the flag is unset.

Example:

IUSE="test"
+RESTRICT="!test? ( test )"
+

+

Rationale: contrary to common assumption, test flag is not special +and the package manager can execute tests when the flag is disabled. +The explicit restriction guarantees that tests will be skipped under +this circumstance, and they will not fail for users.

Note

Technically there are packages that do not strictly require this +restriction since they handle missing test prerequisites gracefully +(e.g. by skipping the tests). However, we enforce the rule for all +packages since omitting the restriction by mistake is much more +common, and there is little harm in overspecifying it.

LICENSE¶

PG: 0704
+
Source: QA
+
Reported: no
+

The LICENSE variable must explicitly list licenses for all files +installed by the package. If some of the applicable licenses are +conditional to USE flags, appropriate USE conditionals need to +be expressed in the variable.

If a package bundles any dependencies that are either installed, +statically linked or in any other way combined with installed files, +the licenses of these dependencies need to be listed as well. This +is not presently required when statically linking to dependencies +installed by separate packages in the repository.

The licenses for files that are not installed but that are used at build +time are not listed explicitly.

Rationale: the primary purpose of the license support in the package +manager is to provide the users with ability to decide on acceptable +licenses for their installed systems (and binary packages). In order +for this to work effectively, the packages must provide a correct +and complete license list.

Static linking combines code from multiple packages, potentially covered +by different licenses. Listing all licenses is the simplest way +of ensuring that nothing is missed, as well as protecting against wrong +derivative work licenses stated upstream (i.e. when a less restrictively +licensed package links to a more restrictively licensed dependency).

Listing of licenses is enforced for bundled dependencies but not for +static linking to other packages, as in the latter case it is +non-trivial to implement and the package manager already verifies +the license while building dependencies (but not when installing binary +packages).

The ebuild format does not provide a separate variable to list licenses +needed only at build time. So far it has not been considered important +enough to have one, as the relevant files exist only temporarily +on the user’s system and do not affect the runtime use of packages.

Note

Please remember to include the licenses of support files provided +by the ebuild, e.g. init.d scripts (usually GPL-2).

USE flags¶

Versioned USE flags¶

PG: 0801
+
Source: QA
+
Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags
+
Reported: no
+

If a need arises to create new USE flags responsible for switching +between multiple versions of a specific dependency, it is recommended +that flat, explicitly versioned flags are used (e.g. qt4, qt5). +The hierarchical form used e.g. by GTK+ (gtk meaning 2-or-3, +then optionally gtk2 or gtk3 to switch between both) +is discouraged.

Any future set of USE flags introduced in this way needs to be discussed +with the QA team before introduction.

Note

This policy has historically been defined as an generalization +of the QA policy on gtk/gtk2/gtk3 flags. The latter policy has been +removed since.

USE=gui flag¶

PG: 0802
+
Source: QA
+
Reference: https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722
+
Reported: no
+

Whenever a package offers an optional GUI support, the gui flag must +be used to control that support rather than historically used X +or toolkit flags. Toolkit flags can still be used to choose between +multiple available GUIs, or when the toolkit is used in a more +specialized way than for GUI (e.g. to control installing widgets).

Rationale: the historical use of toolkit flags to control building +GUIs made it very hard for users to express the simple wish of ‘I want +any GUI’. Installing various packages made it necessary to either +adjust flags per package (manually discovering which flags are necessary +to obtain the GUI) or enabling multiple toolkits globally which +afterwards caused issues with packages supporting a choice between +multiple GUIs.

Underscores in USE flag names¶

PG: 0803
+
Source: Council
+
Reference: https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt
+
Reported: by pkgcheck
+

Underscores are reserved for USE_EXPAND flags, and must not be used +within names of newly-defined regular flags. Existing uses are +considered technically valid, and phasing them out has low priority.

Flags that attempt to resemble USE_EXPAND should be either converted +into proper (global) USE_EXPAND, or made into shorter (unprefixed) +local flags. In other flags, replacing underscore with hyphen is +recommended.

Rationale: a few packages in Gentoo attempted to imitate USE_EXPAND +via local USE flags. This has no clear advantage, may be confusing +to end users who assume that they will work like USE_EXPAND +and in the end unnecessarily lengthens flag names or even causes +unnecessary mismatches between global flags and local flags.

Extending the rule to all flags containing underscores aims to make +distinguishing USE_EXPAND and regular flags easier. It also improves +consistency between flag names that historically used hyphens +or underscores depending on developer’s personal preference.

Users and groups¶

User and group account policy¶

PG: 0901
+
Source: QA
+
Reference: https://bugs.gentoo.org/702460
+
Reported: by repoman and pkgcheck (as deprecated eclass)
+

All new user/group accounts must be created via GLEP 81 packages. +The existing packages should be migrated on the next version bump or +major update.

Existing and historical fixed UIDs/GIDs in range 0..499 (used +in baselayout or via user.eclass) as listed in uid-gid.txt can be reused +as-is in acct-* packages.

UIDs and GIDs in range 0..100 are reserved for important system +accounts. New assignments in that range need to be explicitly approved +by the QA lead, in response to a justified request from the developer.

The range 101..499 is provided for regular use by packages. +The assignments from this range follow the following rules:

A developer can select an arbitrary free UID/GID from this range. +If in doubt, it is recommended to select successive numbers from 499 +downwards.
Unless there is a very good reason not to, matching users and groups +should use the same number. It is acceptable to leave gaps +in assignments as a result of that.
Before pushing the new acct-* packages, the developer must push +an update to uid-gid.txt adding the ‘acct’ entry for the desired +UID/GID. This serves as a synchronization primitive to prevent +collisions.

Further UID/GID ranges will be open in the future as the need arises.

Rationale: this is the second version of the policy for GLEP 81 +packages. It simplifies the process to aid rapid adoption of the new +system. Review requirement and pointless cross-distro syncing were +removed, in favor of a simple process of allocating the next free number +and using it.

The ranges have been chosen to delay the imminent collision between +explicitly reserved UIDs / GIDs and the ones allocated dynamically by +user.eclass (starting from 999 downwards). The lowest GID range has +been reserved for true system users and groups.

Indices and tables¶

Index
Search Page

+ + + + + + + + + +


	+ Dependencies
	+ `PG0001` (Optional runtime dependencies)	+
	+ `PG0002` (=-dependencies with no revision)	+
	+ `PG0003` (Revision bumps on runtime dependency changes)	+
	+ `PG0011` (Slot and subslot dependencies: on (sub-)slotted packages)	+
	+ `PG0012` (Slot and subslot dependencies: special case: Qt packages)	+
	+ `PG0021` (USE dependencies: on packages without the flag)	+

	+ Ebuild file format
	+ `PG0101` (Coding style)	+
	+ `PG0102` (Code must be contained within ebuild and eclasses)	+
	+ `PG0103` (HOMEPAGE must not contain variables)	+
	+ `PG0104` (SRC_URI must not refer to HOMEPAGE)	+
	+ `PG0105` (KEYWORDS must be defined on a single line)	+

	+ File system layout
	+ `PG0201` (Installation paths)	+
	+ `PG0202` (Support for separate /usr)	+
	+ `PG0203` (Strict multilib layout)	+
	+ `PG0204` (Static libraries and libtool files)	+
	+ `PG0205` (Game install locations and ownership)	+
	+ `PG0206` (Absolute symbolic link targets)	+

	+ Installed files
	+ `PG0301` (Installation of small files)	+
	+ `PG0302` (Installation of static libraries)	+
	+ `PG0303` (Installation of libtool (.la) files)	+

	+ Keywording and stabilization
	+ `PG0401` (Rekeywording on dropped keywords)	+
	+ `PG0402` (Stabilizing new versions)	+
	+ `PG0403` (Removing stable keywords)	+

	+ Language-specific policies
	+ `PG0501` (Python: Eclass usage)	+
	+ `PG0502` (Python: Python 2 deprecation)	+

	+ Package Maintainers
	+ `PG0601` (Adding new maintainers)	+
	+ `PG0602` (New packages without a maintainer)	+
	+ `PG0603` (Removing package maintainers)	+

	+ Other metadata variables
	+ `PG0701` (Dynamic slots (multislot flag))	+
	+ `PG0702` (HOMEPAGE value must be meaningful)	+
	+ `PG0703` (RESTRICT=test for USE=-test)	+
	+ `PG0704` (LICENSE)	+

	+ USE flags
	+ `PG0801` (Versioned USE flags)	+
	+ `PG0802` (USE=gui flag)	+
	+ `PG0803` (Underscores in USE flag names)	+

	+ Users and groups
	+ `PG0901` (User and group account policy)	+

Gentoo Policy Guide¶

Preface¶

Introduction¶

Authors¶

License¶

Motivation and history¶

Historical state of policy documentation¶

Purpose of the Policy Guide¶

Basic information¶

Goals of policy making¶

Policy compliance checking¶

Policy enforcement¶

Policy making, changes and appeals¶

Other policy documents¶

Gentoo-specific documentation¶

Package Manager Specification¶

GLEPs¶

Developer Manual¶

External standards¶

POSIX¶

FHS¶

Dependencies¶

Optional runtime dependencies¶

=-dependencies with no revision¶

Slot and subslot dependencies¶

on (sub-)slotted packages¶

special case: Qt packages¶

proactive use of slot operators¶

Revision bumps on runtime dependency changes¶

USE dependencies¶

on packages without the flag¶

Ebuild file format¶

Coding style¶

Code must be contained within ebuild and eclasses¶

HOMEPAGE must not contain variables¶

SRC_URI must not refer to HOMEPAGE¶

KEYWORDS must be defined on a single line¶

File system layout¶

Installation paths¶

Support for separate /usr¶

Strict multilib layout¶

Static libraries and libtool files¶

Game install locations and ownership¶

Absolute symbolic link targets¶

Installed files¶

Installation of small files¶

Installation of static libraries¶

Installation of libtool (.la) files¶

Keywording and stabilization¶

Rekeywording on dropped keywords¶

Stabilizing new versions¶

Removing stable keywords¶

Language-specific policies¶

Python¶

Eclass usage¶

Python 2 deprecation¶

Package Maintainers¶

Adding new maintainers¶

New packages without a maintainer¶

Removing package maintainers¶

Other metadata variables¶

Dynamic slots (multislot flag)¶

HOMEPAGE value must be meaningful¶

RESTRICT=test for USE=-test¶

LICENSE¶

USE flags¶

Versioned USE flags¶

USE=gui flag¶

Underscores in USE flag names¶

Users and groups¶

User and group account policy¶

Indices and tables¶

Policy Index