* [gentoo-commits] proj/policy-guide:master commit in: /, exts/
@ 2020-02-25 15:16 Michał Górny
0 siblings, 0 replies; only message in thread
From: Michał Górny @ 2020-02-25 15:16 UTC (permalink / raw
To: gentoo-commits
commit: 246a7fa1c7e692894f33c3d513779046759213ae
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Feb 22 16:35:48 2020 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Feb 25 15:15:23 2020 +0000
URL: https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=246a7fa1
Introduce PGnnnn identifiers for policies
Introduce stable numeric identifiers for policies, and create permalinks
from them.
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
.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(-)
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)
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2020-02-25 15:16 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-25 15:16 [gentoo-commits] proj/policy-guide:master commit in: /, exts/ Michał Górny
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox