Project:Quality Assurance/Policies

General Notes

 * In the case that a feature of an ebuild violates policy but the QA team has reviewed the situation and given an exception, this should be noted in a comment in the ebuild

USE-Controlled Optional RDEPENDs
We do not have a specific recommendation for how to notify the user of optional dependencies (elogs and readme.gentoo are both viable options), but USE-controlled optional RDEPs are not acceptable except under very specific circumstances, such as a package being nonfunctional unless at least one of a set of RDEPs is installed. If in doubt, ask the QA team to review the situation.

multislot/USE-dependent SLOT
USE=multislot (and other USE-dependent SLOT values) do not belong in the tree. They may be used in overlays, and we consider it acceptable to have eclasses which support multislot as long as it is not used in-tree (so that maintainers do not need to maintain two near-identical versions of the same eclass).

Versioned USE flags
We recommend that in future situations like this (a package can optionally depend on different versions of a library), we recommend the use of versioned USE flags. It should be discussed with the QA team before introduction.

Dropping Stable KEYWORDs
The maintainer may drop stable keyword or last stable version, if arch team does not respond within 90 days; if it breaks the dependency tree, then the maintainer has to work with maintainers of depending packages before dropping keyword/last stable version. The developer should follow the policy for removing a package, except for last rites emails, when removing the last stable version or stable keyword from a package.

Games
The and  directories are deprecated. Games packages should not install any files there, but follow the normal guidelines for install locations instead. Two exceptions are made:
 * 1) Games packages can install files in  (instead of ) if that is the location used by upstream.
 * 2) Shared high-score or game state files can be placed in  or a subdirectory of it.

Reference: Council meeting summary 2015-12-13.

Directories, , , , , and which are shared by multiple packages must have owner root:root and permissions 755 (i.e., the default).

Games that need privileged access to shared high-score or game state files can be installed setgid (mode g+s or 2755). Group "gamestat" with gid 36 (but not the "games" group) should be used for them. The files for state/scores should then be created in or a subdirectory of it and have appropriate owner and permissions (root:gamestat, mode g+w).

Discussion reference: QA team meeting 2015-02-18.

Ebuild code must be wholly contained in ebuild and eclass files
The ebuild code must be wholly contained in files that are defined by the PMS, which as of 2017-03-24 are .ebuild and .eclass files. It is explicitly forbidden to split the ebuild code into additional files that are loaded via source, eval or any other possible method.

Discussion + rationale reference:

GLEP 81 (acct-*) package policy
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. CI system will remind developers to perform the migration.

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:

1. 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.

2. 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.

3. 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.

Policymaking Workflow
When a person brings us problem, we look into the problem and discuss it at meeting. If there is no policy on problem, we make policy; if the policy or documentation is unclear, we update it. If the policy is actively being ignored we politely ask the person to stop. It is more reactive than proactive, this does not preclude emergency action on our part. This will give the team the time to work out basic rules and workflows, we might do more proactive tasks later one, if there is any need for them. However, if we think somebody is breaking the tree, we can ask them to stop and/or undo what they did pending a review at a QA meeting.

Communicating New Policy
Emailing gentoo-dev@ and gentoo-dev-announce@ and updating this wiki page are the minimum for announcing new policies. Blog posts are also encouraged.

Communication When Making Fixes
We fix and send a friendly reminder to the maintainer(s) for trivial fixes; open bug, wait 2 weeks, make the change for larger but non-critical fixes; make the change and send a notification for critical fixes.

Action Policy and Internal Dispute Resolution
QA team members may act on their own. All internal disagreements on said actions must be handled privately between QA members. The Lead/Deputy may revert any action if they believe it was a mistake, but they will be held responsible for that change. Any action which is disputed can be settled by a team vote, and the result of that vote will be the final decision.