summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichał Górny <mgorny@gentoo.org>2020-01-08 12:47:08 +0100
committerMichał Górny <mgorny@gentoo.org>2020-01-08 12:47:08 +0100
commitda119a485dcfe3fe77227777a2b440c4c8a8453f (patch)
tree11e1e434990b3b19c3ef62e50db166f06ffeb38f
parentdependencies: revbumps (diff)
downloadpolicy-guide-da119a485dcfe3fe77227777a2b440c4c8a8453f.tar.gz
policy-guide-da119a485dcfe3fe77227777a2b440c4c8a8453f.tar.bz2
policy-guide-da119a485dcfe3fe77227777a2b440c4c8a8453f.zip
USE flags
Signed-off-by: Michał Górny <mgorny@gentoo.org>
-rw-r--r--conf.py2
-rw-r--r--use-flags.rst60
2 files changed, 61 insertions, 1 deletions
diff --git a/conf.py b/conf.py
index 25ec69e..15c2c65 100644
--- a/conf.py
+++ b/conf.py
@@ -38,7 +38,7 @@ release = ''
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = ['sphinx.ext.todo']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/use-flags.rst b/use-flags.rst
new file mode 100644
index 0000000..64b1987
--- /dev/null
+++ b/use-flags.rst
@@ -0,0 +1,60 @@
+USE flags
+=========
+
+.. index::
+ single: USE flags; gtk
+ pair: USE flags; Qt
+ single: USE flags; versioned
+
+Versioned USE flags
+-------------------
+: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.
+
+.. TODO:: rationale
+
+.. 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.
+
+
+.. index:: USE flags; underscore
+
+Underscores in USE flag names
+-----------------------------
+: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.