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

gtk/gtk2/gtk3 USE flag situation
We mandate that gtk move to versioned USE flags. For simplicity of migration, we will allow USE=gtk to mean "depend on gtk2," since there are only a few USE=gtk2 remaining in tree. USE=gtk3 will mean "depend on gtk3." Future USE flags should follow the same pattern, with gtk4 meaning "depend on gtk4," etc. USE=gtk may not be used to mean "depend on some version of gtk."

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 PMS 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: bug #612630

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.