From 246a7fa1c7e692894f33c3d513779046759213ae Mon Sep 17 00:00:00 2001 From: Michał Górny Date: Sat, 22 Feb 2020 17:35:48 +0100 Subject: Introduce PGnnnn identifiers for policies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduce stable numeric identifiers for policies, and create permalinks from them. Signed-off-by: Michał Górny --- .gitignore | 1 + conf.py | 13 ++++++++----- dependencies.rst | 6 ++++++ ebuild-format.rst | 5 +++++ exts/policyident.py | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ filesystem.rst | 6 ++++++ installed-files.rst | 3 +++ keywords.rst | 3 +++ languages.rst | 2 ++ maintainer.rst | 3 +++ other-metadata.rst | 4 ++++ use-flags.rst | 3 +++ user-group.rst | 1 + 13 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 exts/policyident.py 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/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/ebuild-format.rst b/ebuild-format.rst index ed9bde0..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 @@ -73,6 +76,7 @@ as reducing the usefulness of plain tools such as grep. SRC_URI must not refer to HOMEPAGE ---------------------------------- +:PG: 0104 :Source: QA :Reported: by pkgcheck @@ -92,6 +96,7 @@ index. KEYWORDS must be defined on a single line ----------------------------------------- +:PG: 0105 :Source: QA :Reported: no diff --git a/exts/policyident.py b/exts/policyident.py new file mode 100644 index 0000000..6093c8c --- /dev/null +++ b/exts/policyident.py @@ -0,0 +1,48 @@ +# Handle :PG: policy identifiers for Policy Guide +# (c) 2020 Michał Górny +# 2-clause BSD license + +from docutils import nodes + +from sphinx.util import logging + + +logger = logging.getLogger(__name__) + + +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 + + 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)) + return iv + + logger.warning('%s: no PG identifier found', title.astext()) + + +def on_doctree_read(app, doctree): + for node in doctree.traverse(nodes.section): + pg_id = find_pg_id(node) + if pg_id is not None: + node['ids'].insert(0, 'pg' + pg_id) + + +def setup(app): + app.connect('doctree-read', on_doctree_read) + return { + 'version': '0', + } 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 14651cf..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 @@ -98,6 +101,7 @@ this circumstance, and they will not fail for users. LICENSE ------- +:PG: 0704 :Source: QA :Reported: no 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) -- cgit v1.2.3-65-gdbad