summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--Makefile5
-rw-r--r--conf.py13
-rw-r--r--dependencies.rst6
-rw-r--r--deprecation.rst37
-rw-r--r--ebuild-format.rst23
-rw-r--r--exts/policyident.py128
-rw-r--r--filesystem.rst6
-rw-r--r--installed-files.rst3
-rw-r--r--keywords.rst3
-rw-r--r--languages.rst2
-rw-r--r--maintainer.rst3
-rw-r--r--other-metadata.rst53
-rw-r--r--tox.ini4
-rw-r--r--use-flags.rst3
-rw-r--r--user-group.rst1
16 files changed, 282 insertions, 9 deletions
diff --git a/.gitignore b/.gitignore
index 301101c..ea5fde5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
/_build/
/.tox/
+/exts/__pycache__/
diff --git a/Makefile b/Makefile
index 5168496..b5027c9 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,10 @@ SPHINXPROJ = GentooPolicyGuide
SOURCEDIR = .
BUILDDIR = _build
-all: html
+all: html $(BUILDDIR)/html/combined.html
+
+$(BUILDDIR)/html/combined.html: singlehtml
+ cp $(BUILDDIR)/singlehtml/index.html $@
.PHONY: all Makefile
diff --git a/conf.py b/conf.py
index e91b613..d622b02 100644
--- a/conf.py
+++ b/conf.py
@@ -11,10 +11,10 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('exts'))
# -- Project information -----------------------------------------------------
@@ -38,7 +38,10 @@ 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 = ['sphinx.ext.todo']
+extensions = [
+ 'policyident',
+ 'sphinx.ext.todo',
+]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/dependencies.rst b/dependencies.rst
index 55bba5c..a1f5177 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -6,6 +6,7 @@ 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
@@ -35,6 +36,7 @@ This is especially important for packages that take long time to build.
=-dependencies with no revision
-------------------------------
+:PG: 0002
:Source: QA
:Reported: by repoman and pkgcheck
@@ -67,6 +69,7 @@ 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
@@ -100,6 +103,7 @@ means 'verified that any slot is acceptable'.
special case: Qt packages
~~~~~~~~~~~~~~~~~~~~~~~~~
+:PG: 0012
:Source: Qt project
:Reference: https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies
:Reported: no
@@ -132,6 +136,7 @@ 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
@@ -175,6 +180,7 @@ USE dependencies
on packages without the flag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:PG: 0021
:Source: QA (inferred from PMS)
:Reported: by pkgcheck
diff --git a/deprecation.rst b/deprecation.rst
new file mode 100644
index 0000000..c0badd0
--- /dev/null
+++ b/deprecation.rst
@@ -0,0 +1,37 @@
+Deprecations
+============
+
+
+.. index:: EAPI; deprecated
+
+Deprecated EAPIs
+----------------
+:PG: 1001
+:Source: Council
+:Reference: https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/layout.conf
+:Reported: by pkgcheck and repoman
+
+Deprecated EAPIs should not be used in new ebuilds. Existing packages
+should be migrated to newer EAPIs on version bumps, or proactively when
+no version bumps are expected.
+
+The current list of deprecated EAPIs is stored as ``eapis-deprecated``
+in ``metadata/layout.conf``.
+
+
+.. index:: eclass; deprecated
+
+Deprecated eclasses
+-------------------
+:PG: 1003
+:Source: individual eclass maintainers
+:Reference: https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/qa-policy.conf
+:Reported: by pkgcheck and repoman
+
+Deprecated eclasses should not be used in new ebuilds. Existing
+packages should be updated not to use these eclasses on version bumps,
+or proactively when no version bumps are expected.
+
+The current list of deprecated eclasses is stored along with suggested
+replacements as ``deprecated-eclass`` section
+of ``metadata/qa-policy.conf``.
diff --git a/ebuild-format.rst b/ebuild-format.rst
index d2c8dc5..a5bf5aa 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -8,6 +8,7 @@ Ebuild file format
Coding style
------------
+:PG: 0101
:Source: QA
:Reported: partially via repoman and pkgcheck
@@ -32,6 +33,7 @@ the ebuild.
Code must be contained within ebuild and eclasses
-------------------------------------------------
+:PG: 0102
:Source: QA
:Reference: https://bugs.gentoo.org/612630
:Reported: no
@@ -54,6 +56,7 @@ that possibility, including linting tools.
HOMEPAGE must not contain variables
-----------------------------------
+:PG: 0103
:Source: QA
:Reported: by pkgcheck, highlighted as error by gentoo-syntax
@@ -68,12 +71,12 @@ preprocessing, breaking URI support in terminals and editors, as well
as reducing the usefulness of plain tools such as grep.
-
.. index::
pair: src uri; homepage
SRC_URI must not refer to HOMEPAGE
----------------------------------
+:PG: 0104
:Source: QA
:Reported: by pkgcheck
@@ -87,3 +90,21 @@ 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.
+
+
+.. index:: keywords; one line
+
+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.
diff --git a/exts/policyident.py b/exts/policyident.py
new file mode 100644
index 0000000..9679bba
--- /dev/null
+++ b/exts/policyident.py
@@ -0,0 +1,128 @@
+# Handle :PG: policy identifiers for Policy Guide
+# (c) 2020 Michał Górny
+# 2-clause BSD license
+
+import collections
+
+from docutils import nodes
+
+from sphinx.domains import Index
+from sphinx.environment.collectors.toctree import TocTreeCollector
+from sphinx.util import logging
+
+
+logger = logging.getLogger(__name__)
+
+Policy = collections.namedtuple('Policy', ('id', 'title', 'docname',
+ 'chapter'))
+
+toccollector = TocTreeCollector()
+
+
+class PolicyIndex(Index):
+ name = 'policy-index'
+ localname = 'Policy Index'
+ shortname = 'Policy Index'
+
+ def generate(self, docnames=None):
+ env = self.domain.env
+ if not hasattr(env, 'policy_index'):
+ env.policy_index = []
+
+ entries = collections.defaultdict(list)
+ for p in env.policy_index:
+ if docnames is not None and p.docname not in docnames:
+ continue
+ entries[p.chapter].append(('PG' + p.id, # name
+ 0, # subtype
+ p.docname, # docname
+ 'pg' + p.id, # anchor
+ p.title, # extra
+ '', # qualifier
+ '')) # descr
+
+ return (sorted([(k, sorted(v)) for k, v in entries.items()],
+ key=lambda kv: kv[1]),
+ False)
+
+
+def find_pg_id(section):
+ # first child should be title
+ title = section.children[0]
+ assert isinstance(title, nodes.title)
+ # second child should be field list
+ cl = section.children[1]
+ if not isinstance(cl, nodes.field_list):
+ return None, title.astext(), None
+
+ for f in cl.traverse(nodes.field):
+ fn = next(iter(f.traverse(nodes.field_name)))
+ fv = next(iter(f.traverse(nodes.field_body)))
+ if fn.astext().upper() == 'PG':
+ if fn.astext() != 'PG':
+ raise RuntimeError('PG field must be uppercase')
+ iv = '{:04d}'.format(int(fv.astext(), 10))
+ if fv.astext() != iv:
+ raise RuntimeError('PG value must be 4 digits, zero-padded ({})'
+ .format(iv))
+
+ el = section
+ titles = []
+ while el.parent is not None:
+ title = el.children[0]
+ assert isinstance(title, nodes.title)
+ titles.append(title.astext())
+ el = el.parent
+ # combine all section titles up to but excluding
+ # the chapter title
+ title = ': '.join(reversed(titles[:-1]))
+
+ return iv, title, titles[-1]
+
+ logger.warning('%s: no PG identifier found', title.astext())
+ return None, title.astext(), None
+
+
+def on_doctree_read(app, doctree):
+ env = app.builder.env
+ if not hasattr(env, 'policy_index'):
+ env.policy_index = []
+
+ for node in doctree.traverse(nodes.section):
+ pg_id, title, chapter = find_pg_id(node)
+ if pg_id is not None:
+ node['ids'].insert(0, 'pg' + pg_id)
+ env.policy_index.append(Policy(pg_id, title, env.docname,
+ chapter))
+
+ # update the table of conents to use the 'pgXXXX' ids
+ toccollector.process_doc(app, doctree)
+
+
+def on_env_purge_doc(app, env, docname):
+ if not hasattr(env, 'policy_index'):
+ return
+
+ env.policy_index = [p for p in env.policy_index
+ if p.docname != docname]
+
+
+def on_env_merge_info(app, env, docnames, other):
+ if not hasattr(other, 'policy_index'):
+ return
+ if not hasattr(env, 'policy_index'):
+ env.policy_index = []
+
+ env.policy_index.extend(other.policy_index)
+
+
+def setup(app):
+ app.connect('doctree-read', on_doctree_read)
+ app.connect('env-purge-doc', on_env_purge_doc)
+ app.connect('env-merge-info', on_env_merge_info)
+ app.add_index_to_domain('std', PolicyIndex)
+ return {
+ 'version': '0',
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
diff --git a/filesystem.rst b/filesystem.rst
index 081ab99..52e20a3 100644
--- a/filesystem.rst
+++ b/filesystem.rst
@@ -5,6 +5,7 @@ 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
@@ -60,6 +61,7 @@ exceptions are:
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
@@ -79,6 +81,7 @@ 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
@@ -103,6 +106,7 @@ 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
@@ -124,6 +128,7 @@ 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
@@ -160,6 +165,7 @@ fulfill that purpose.
Absolute symbolic link targets
------------------------------
+:PG: 0206
:Source: QA
:Reported: by repoman and pkgcheck (when ebuild-generated)
diff --git a/installed-files.rst b/installed-files.rst
index b77bc02..c8c55f2 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -7,6 +7,7 @@ Installed files
Installation of small files
---------------------------
+:PG: 0301
:Source: QA
:Reported: no
@@ -40,6 +41,7 @@ such a huge package in order to install one tiny file.
Installation of static libraries
--------------------------------
+:PG: 0302
:Source: QA
:Reported: no
@@ -61,6 +63,7 @@ libraries if they are never going to be used.
Installation of libtool (.la) files
-----------------------------------
+:PG: 0303
:Source: QA
:Reported: no
diff --git a/keywords.rst b/keywords.rst
index 272dca4..81db271 100644
--- a/keywords.rst
+++ b/keywords.rst
@@ -5,6 +5,7 @@ Keywording and stabilization
Rekeywording on dropped keywords
--------------------------------
+:PG: 0401
:Source: QA
:Reported: by pkgcheck and repoman
@@ -23,6 +24,7 @@ a new version or to remove an old version.
Stabilizing new versions
------------------------
+:PG: 0402
:Source: QA
:Reported: by pkgcheck
@@ -50,6 +52,7 @@ 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
diff --git a/languages.rst b/languages.rst
index b84a80c..dc3a142 100644
--- a/languages.rst
+++ b/languages.rst
@@ -13,6 +13,7 @@ Python
Eclass usage
~~~~~~~~~~~~
+:PG: 0501
:Source: Python project
:Reference: https://wiki.gentoo.org/wiki/Project:Python/Eclasses
:Reported: by pkgcheck
@@ -41,6 +42,7 @@ 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
diff --git a/maintainer.rst b/maintainer.rst
index 07dd3b1..e37daf4 100644
--- a/maintainer.rst
+++ b/maintainer.rst
@@ -5,6 +5,7 @@ Package Maintainers
Adding new maintainers
----------------------
+:PG: 0601
:Source: QA
:Reported: no
@@ -31,6 +32,7 @@ them from packages actually within project's profile was hard.
New packages without a maintainer
---------------------------------
+:PG: 0602
:Source: QA
:Reported: no
@@ -50,6 +52,7 @@ to take care of them.
Removing package maintainers
----------------------------
+:PG: 0603
:Source: QA
:Reported: no
diff --git a/other-metadata.rst b/other-metadata.rst
index f05014b..c59e0c2 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -6,6 +6,7 @@ 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
@@ -42,6 +43,7 @@ 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
@@ -69,6 +71,7 @@ easy to identify such packages.
RESTRICT=test for USE=-test
---------------------------
+:PG: 0703
:Source: QA
:Reported: by pkgcheck
@@ -94,4 +97,54 @@ this circumstance, and they will not fail for users.
common, and there is little harm in overspecifying it.
+.. index:: license
+
+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).
+
+
.. _metadata invariance: https://projects.gentoo.org/pms/7/pms.html#x1-600007.1
diff --git a/tox.ini b/tox.ini
index 2261cc5..faedab9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,9 +5,9 @@ skipsdist = True
[testenv]
deps =
sphinx
- git+https://github.com/mmagorsc/tyrian_sphinx_theme/#egg=tyrian_sphinx_theme
+ tyrian-sphinx-theme
whitelist_externals =
make
commands =
- make {posargs:html}
+ make {posargs:all}
diff --git a/use-flags.rst b/use-flags.rst
index c6a8b4a..4344edc 100644
--- a/use-flags.rst
+++ b/use-flags.rst
@@ -8,6 +8,7 @@ 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
@@ -38,6 +39,7 @@ with the QA team before introduction.
USE=gui flag
------------
+:PG: 0802
:Source: QA
:Reference: https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722
:Reported: no
@@ -61,6 +63,7 @@ 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
diff --git a/user-group.rst b/user-group.rst
index 389f3b9..09944a5 100644
--- a/user-group.rst
+++ b/user-group.rst
@@ -6,6 +6,7 @@ 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)