[gentoo-commits] proj/policy-guide:master commit in: /

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     dfeecf62f875f4a00de666b17902701da64576ad
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 23 08:30:35 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Apr 23 08:30:35 2022 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=dfeecf62

ebuild-format: LICENSE must not contain variable references

As discussed in #gentoo-qa.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-format.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/ebuild-format.rst b/ebuild-format.rst
index a5bf5aa..041c088 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -108,3 +108,21 @@ wrapping, appending, etc.).
 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.
+
+
+.. index:: license; variable
+
+LICENSE must not contain variables
+----------------------------------
+:PG: 0106
+:Source: QA
+:Reported: no
+
+The ``LICENSE`` variable in an ebuild must specify all the license names
+verbatim, without referring to any variables.  The only exception is
+(implicit or explicit) use of ``LICENSE`` itself, i.e. appending is
+allowed.
+
+*Rationale*: since license names do not contain dynamic parts (such as
+package versions), using variables there has little advantage.  On the
+other hand, variables reduce the usefulness of plain tools such as grep.

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     13d3447c0847c11077316a7e2a3d436162a7d901
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat May 18 12:58:33 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat May 18 12:58:33 2024 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=13d3447c

dependencies: Fix a typo in PG 0021

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 dependencies.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dependencies.rst b/dependencies.rst
index c0afb81..21c8b69 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -195,7 +195,7 @@ only versions having the flag.
 
     # BAD: USE=gtk2 is not supported by v2
     dev-foo/libfrobnicate[gtk2]
-    # GOOD: all matching versions have USE=tools
+    # GOOD: all matching versions have USE=gtk2
     <dev-foo/libfrobnicate-2[gtk2]
     # GOOD: indicate the default
     dev-foo/libfrobnicate[gtk2(-)]

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     ef101e94ed2a081736a7efba696af9321d3e7850
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Fri Sep  1 10:31:06 2023 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Fri Sep  1 10:31:06 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=ef101e94

tox: Use our fork of tyrian-sphinx-theme

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 tox.ini | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/tox.ini b/tox.ini
index d80cb19..dc18983 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,8 +4,9 @@ skipsdist = True
 
 [testenv]
 deps =
-	sphinx<7
-	tyrian-sphinx-theme
+	sphinx
+	# until we reclaim the pypi project
+	git+https://anongit.gentoo.org/git/proj/tyrian-sphinx-theme.git
 allowlist_externals =
 	make
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     a602b78d73ce5d562b44185fbf82fc03a2f18c2d
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Aug 17 21:45:50 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Aug 17 21:45:50 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=a602b78d

tox.ini, conf.py: Make it build

Depend on sphinx<7 and change language to 'en'.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 conf.py | 2 +-
 tox.ini | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/conf.py b/conf.py
index d622b02..0f006dc 100644
--- a/conf.py
+++ b/conf.py
@@ -60,7 +60,7 @@ master_doc = 'index'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/tox.ini b/tox.ini
index dbb2876..d80cb19 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,7 +4,7 @@ skipsdist = True
 
 [testenv]
 deps =
-	sphinx
+	sphinx<7
 	tyrian-sphinx-theme
 allowlist_externals =
 	make

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     f49883323267b30ec167257002be8324a5c524cf
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Aug 16 17:05:10 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Aug 17 20:55:16 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=f4988332

filesystem: Disallow subdirs in /bin and its friends (PG 0201)

The FHS says that directories /bin, /sbin and their counterparts in
/usr don't contain any subdirectories:
https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s04.html#requirements2
https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s16.html#requirements8
https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s04.html#requirements9a
https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s10.html#requirements10a

Packages that need specific subdirs for binaries should install them
in /usr/lib or /usr/libexec.

Bug: https://bugs.gentoo.org/912354
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 filesystem.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/filesystem.rst b/filesystem.rst
index 52e20a3..f3b8cdf 100644
--- a/filesystem.rst
+++ b/filesystem.rst
@@ -27,6 +27,8 @@ directories:
    - /usr
    - /var
 
+There must be no subdirectories in /bin and /sbin.
+
 Furthermore, only the following subdirectories of /usr are permitted:
 
 .. hlist::
@@ -41,6 +43,8 @@ Furthermore, only the following subdirectories of /usr are permitted:
    - /usr/src
    - /usr/<triplet>
 
+There must be no subdirectories in /usr/bin and /usr/sbin.
+
 Furthermore, within /usr/share/doc hierarchy only a subdirectory named
 after full package name and version with revision (PF) is permitted.
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     bf68ca3759a258a121e05f98b1d20960d8a6a617
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 18 17:27:11 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Jan 18 17:27:11 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=bf68ca37

installed-files: Policy against use-conditional manpages

Closes: https://bugs.gentoo.org/689684
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 installed-files.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/installed-files.rst b/installed-files.rst
index 19e72e4..6ccc1be 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -114,3 +114,23 @@ an empty installation image.  Package managers rely on this for some
 optimizations.  Also QA tools make certain assumptions about virtuals,
 e.g., that they must not assign the ``LICENSE`` variable (which would
 be impossible if they installed any files).
+
+
+.. index::
+   pair: installed files; manpages
+
+Installation of manpages
+------------------------
+:PG: 0305
+:Source: QA
+:Reported: no
+
+Packages must not disable installing manpages via USE flags (e.g.
+``USE=man`` or ``USE=doc``).  If upstream does not ship prebuilt
+manpages and building them requires additional dependencies,
+the maintainer should build them and ship along with the package.
+
+*Rationale*: Manpages are basic documentation for installed software.
+While additional dependencies are inconvenient for users, not building
+manpages is harmful.  Including (optionally or unconditionally)
+prebuilt manpages is a good compromise.

[gentoo-commits] proj/policy-guide:master commit in: /

[Sam James]

commit:     23ddd2ec2b5d5066e3a049e7b13f73f3cce2afdf
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Tue Jan 21 17:09:33 2020 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 18:45:01 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=23ddd2ec

Add a section on editing and publishing

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/10
Signed-off-by: Sam James <sam <AT> gentoo.org>

 editing.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 index.rst   |  1 +
 2 files changed, 87 insertions(+)

diff --git a/editing.rst b/editing.rst
new file mode 100644
index 0000000..a12ff0b
--- /dev/null
+++ b/editing.rst
@@ -0,0 +1,86 @@
+Editing and publishing updates to this Guide
+============================================
+
+Formatting and style
+--------------------
+While editing the Guide, please respect the existing formatting rules.
+Notably:
+
+- wrap lines at 72 characters
+- two spaces between sentences (after full stop), one space otherwise
+- one empty line between titles and paragraphs, two empty lines between
+  text and next section
+- indent using spaces, aligning to previous line
+
+When adding a new rule, use the chapter with a fitting topic.  Some
+rules match multiple chapters, choose the one that fits it best.  Make
+sure to match existing keywords in index.
+
+
+Getting sources
+---------------
+The reference repository is hosted at git.gentoo.org, and available
+via `proj/policy-guide.git gitweb`_.  To clone it::
+
+    # via https
+    git clone https://anongit.gentoo.org/git/proj/policy-guide.git
+    # via ssh
+    git clone git@git.gentoo.org:proj/policy-guide.git
+
+Non-developers wishing to send pull requests may prefer to fork
+the GitHub `gentoo/policy-guide repository`_ and clone their own fork
+instead.
+
+
+Building
+--------
+A tox-file is provided to build the Guide in a virtualenv, installing
+all necessary dependencies.  To build the HTML version, run::
+
+    tox
+
+Another format (as well as other make arguments) can be specified
+as a command-line argument, e.g.::
+
+    tox latexpdf
+
+
+Sending contributions
+---------------------
+Changes to this document can be either submitted to `Policy Manual
+Gentoo Bugzilla component`_ as git-format patches attached to the bugs,
+or to `gentoo/policy-guide repository`_ as pull requests.
+
+
+Merging pull requests
+---------------------
+The recommended way to merge pull requests is to use
+``app-portage/pram``.  To configure the remote before the first use,
+run the following command in your checkout::
+
+    git config --replace-all pram.repo gentoo/policy-guide
+
+Afterwards, call the tool to merge pull request by number::
+
+    pram N
+
+
+Publishing
+----------
+The built version of Policy Guide is currently published via a git
+repository.  The recommended method is to clone the repository
+into ``_build/html`` in order to make Sphinx output into the checkout::
+
+    rm -r _build/html
+    git clone git@git.gentoo.org:sites/projects/qa/policy-guide.git \
+        _build/html
+
+Commit and push all the changes after rebuilding the Guide.
+
+
+.. _proj/policy-guide.git gitweb:
+   https://gitweb.gentoo.org/proj/policy-guide.git/
+.. _gentoo/policy-guide repository:
+   https://github.com/gentoo/policy-guide
+.. _Policy Manual Gentoo Bugzilla component:
+   https://bugs.gentoo.org/enter_bug.cgi?product=Documentation&component=Policy+Guide

diff --git a/index.rst b/index.rst
index b3bcddc..1978cc8 100644
--- a/index.rst
+++ b/index.rst
@@ -17,6 +17,7 @@ in which the policy can be updated.
    motivation
    basics
    other-docs
+   editing
    *
 
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Sam James]

commit:     75164c2f72aed07cbea40e95cfedbe775f8a377a
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Apr 24 17:04:55 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 18:45:09 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=75164c2f

Makefile: use a custom `clean` target

Replace the Sphinx's `clean` target with a custom one that does not
remove the git repository from _build/html.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Sam James <sam <AT> gentoo.org>

 Makefile | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index b5027c9..e640808 100644
--- a/Makefile
+++ b/Makefile
@@ -13,7 +13,11 @@ all: html $(BUILDDIR)/html/combined.html
 $(BUILDDIR)/html/combined.html: singlehtml
 	cp $(BUILDDIR)/singlehtml/index.html $@
 
-.PHONY: all Makefile
+# The standard `clean` command removes the git repository
+clean:
+	rm -rf _build/html/* _build/html/.buildinfo
+
+.PHONY: all clean Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

[gentoo-commits] proj/policy-guide:master commit in: /

[Sam James]

commit:     0e263fcbe0437c3a82e2314955e6722d9047b193
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Apr 24 17:05:41 2022 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 18:45:09 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=0e263fcb

tox.ini: Call `make clean`

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/23
Signed-off-by: Sam James <sam <AT> gentoo.org>

 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index ceb90c0..dbb2876 100644
--- a/tox.ini
+++ b/tox.ini
@@ -10,4 +10,4 @@ allowlist_externals =
 	make
 
 commands =
-	make {posargs:all}
+	make {posargs:clean all}

[gentoo-commits] proj/policy-guide:master commit in: /

[Sam James]

commit:     7c1c4de9056cf0377ad629a0698cfdb36a743585
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Thu May 28 15:52:24 2020 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 18:45:39 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=7c1c4de9

installed-files: Indicate when .a files can be removed in install

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/18
Signed-off-by: Sam James <sam <AT> gentoo.org>

 installed-files.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/installed-files.rst b/installed-files.rst
index 1468288..19e72e4 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -57,6 +57,14 @@ really necessary (e.g. for recovery tools) but otherwise proliferating
 it is considered harmful.  There is no point in installing static
 libraries if they are never going to be used.
 
+.. Note::
+
+   If the package's build system does not support disabling static
+   library build, it is recommended to patch it and submit the patch
+   upstream.  However, if that is not feasible and building both shared
+   and static libraries does not require compiling source files twice,
+   it is acceptable to strip static libraries in ``src_install()``.
+
 
 .. index::
    pair: installed files; libtool file

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     bd2e308f5620ddcadc431feac7f0d5f02cb237fb
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 14 18:34:08 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 18:34:08 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=bd2e308f

ebuild-format: D in other phases is reported by pkgcheck

VariableScope: version 1: variable 'D' used in 'src_configure' on line: 23

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-format.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-format.rst b/ebuild-format.rst
index a381e07..039e897 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -134,7 +134,7 @@ D must be used only in src_install and pkg_preinst
 --------------------------------------------------
 :PG: 0107
 :Source: QA
-:Reported: no
+:Reported: by pkgcheck
 
 The ``D`` and ``ED`` variables must be used only in the ``src_install``
 and ``pkg_preinst`` phase functions.  Exceptions to this policy can be

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     d1ba6fd44598066a28233294749b489577f019ba
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 14 17:30:26 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Jan 14 17:30:26 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=d1ba6fd4

tox.ini: whitelist was renamed to allowlist

... wasting everybody's time for no reason. :(

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index faedab9..ceb90c0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -6,7 +6,7 @@ skipsdist = True
 deps =
 	sphinx
 	tyrian-sphinx-theme
-whitelist_externals =
+allowlist_externals =
 	make
 
 commands =

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     a3606dbf00df04ec36e0f2f2f49a6f5527ce4a58
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Jan 13 08:30:32 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jan 13 08:30:32 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=a3606dbf

preface: Add myself as author

Main author of PG 0106, 0107, 0304, and some contributions to other
policies.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 preface.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/preface.rst b/preface.rst
index 85344d4..e0af2d9 100644
--- a/preface.rst
+++ b/preface.rst
@@ -19,6 +19,7 @@ This document is maintained by the Gentoo `QA project`_.
 The current text authors are:
 
 - Michał Górny (mgorny)
+- Ulrich Müller (ulm)
 
 
 License

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     92bb5e10171165b681c3ec526d90a1508e6dc9fa
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Jul 24 17:15:42 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Mon Jul 25 16:08:46 2022 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=92bb5e10

other-metadata: Sync with the updated LICENSE policy in the devmanual

See commit 4a74d85 in the proj/devmanual repository:

By the FSF's definition (see for example GPL-3):
"The 'Corresponding Source' for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities."

It makes much sense to apply this as a general definition. Applying it
only to GPL licensed packages would mean:
- We would need another case distinction, making the rules for LICENSE
  even more complicated.
- As an example, consider a MIT licensed package with a CDDL licensed
  (i.e., GPL incompatible) build script: If that package was a library,
  then it couldn't be linked against a GPL licensed package, whereas
  a LICENSE variable listing only MIT would falsely indicate that it
  could.

Closes: https://bugs.gentoo.org/860552
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 other-metadata.rst | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/other-metadata.rst b/other-metadata.rst
index d79ef6f..d3c98fd 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -105,10 +105,12 @@ LICENSE
 :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.
+The ``LICENSE`` variable must explicitly list all licenses pertaining
+to the "corresponding source" of the files installed by the package.
+This includes all their source code, but also all scripts used to
+control compilation and installation.  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,
@@ -116,8 +118,8 @@ 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.
+The licenses for files that are neither installed nor used at build
+time shall not be listed.
 
 *Rationale*: the primary purpose of the license support in the package
 manager is to provide the users with ability to decide on acceptable
@@ -137,11 +139,6 @@ 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).

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     12f1e30e82a0ecedd91e77edfbb519366edb17b0
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Jan 13 07:49:00 2023 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jan 13 08:04:54 2023 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=12f1e30e

ebuild-format: Restrict D to src_install and pkg_preinst

This used to be specified in PMS (see commit ede65b5 in proj/pms.git),
but makes more sense as a tree policy.

Also exclude pkg_postinst, because nothing in the Gentoo repository
appears to use D there, and in the postinst phase the directory will
be empty of files anyway.

Bug: https://bugs.gentoo.org/890624
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-format.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/ebuild-format.rst b/ebuild-format.rst
index 041c088..a381e07 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -126,3 +126,21 @@ allowed.
 *Rationale*: since license names do not contain dynamic parts (such as
 package versions), using variables there has little advantage.  On the
 other hand, variables reduce the usefulness of plain tools such as grep.
+
+
+.. index:: d; variable
+
+D must be used only in src_install and pkg_preinst
+--------------------------------------------------
+:PG: 0107
+:Source: QA
+:Reported: no
+
+The ``D`` and ``ED`` variables must be used only in the ``src_install``
+and ``pkg_preinst`` phase functions.  Exceptions to this policy can be
+granted by the QA team.
+
+*Rationale*: using ``D`` in other phases (e.g. ``src_configure``) is
+error-prone and may lead to the path being embedded in files of the
+installed image.  In addition, the directory pointed to by ``${D}``
+does not exist in other phases.

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     48c7ed27d229014f560f0be4d4eda8dab4d1ec7d
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Apr 26 19:32:22 2022 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Apr 26 19:32:22 2022 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=48c7ed27

installed-files: Restrict find to regular files

Rationale: libtool .la files are regular files, therefore find -type f
is more correct in this context.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 installed-files.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/installed-files.rst b/installed-files.rst
index da6263e..1468288 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -79,7 +79,7 @@ b. the package is installing static libraries that have additional
 
 It is recommended to use the following one-liner to remove .la files::
 
-    find "${ED}" -name '*.la' -delete || die
+    find "${ED}" -type f -name '*.la' -delete || die
 
 *Rationale*: libtool files were historically introduced as an attempt
 to supplement static library archives with dependent library list.

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     b1ce71b478e916e3b55da5235ef285d35a8ac31e
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Nov 14 20:38:50 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Mon Nov 15 13:09:30 2021 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=b1ce71b4

user-group: Update according to today's Council decision

Also change the order from downwards to upwards, so that we start
allocation in the new range 500..749 progressing upwards.

For the existing range 101..499 order doesn't really matter, because
it is practically full (as of today, 15 free UIDs and no free GIDs).

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 user-group.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/user-group.rst b/user-group.rst
index 09944a5..320d2e4 100644
--- a/user-group.rst
+++ b/user-group.rst
@@ -23,12 +23,12 @@ UIDs and GIDs in range 0..100 are reserved for important system
 accounts.  New assignments in that range need to be explicitly approved
 by the QA lead, in response to a justified request from the developer.
 
-The range 101..499 is provided for regular use by packages.
+The range 101..749 is provided for regular use by packages.
 The assignments from this range follow the following rules:
 
 1. A developer can select an arbitrary free UID/GID from this range.
-   If in doubt, it is recommended to select successive numbers from 499
-   downwards.
+   If in doubt, it is recommended to select successive numbers from 101
+   upwards.
 
 2. Unless there is a very good reason not to, matching users and groups
    should use the same number.  It is acceptable to leave gaps

[gentoo-commits] proj/policy-guide:master commit in: /

[Sam James]

commit:     ddffad701aa2ea6b95d3916f8cfa45cb5ac2ff97
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Mon Sep 20 03:40:57 2021 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Mon Nov 15 04:19:34 2021 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=ddffad70

other-metadata: Add bug reference re multislot flag

Bug: https://bugs.gentoo.org/174407
Signed-off-by: Sam James <sam <AT> gentoo.org>

 other-metadata.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/other-metadata.rst b/other-metadata.rst
index c59e0c2..d79ef6f 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -8,7 +8,7 @@ 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
+:Reference: https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT, https://bugs.gentoo.org/174407
 :Reported: ``use`` in global scope triggers fatal error
 
 The use of ``multislot`` to alter ``SLOT`` values (as well as any other

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     61a556871641021583d222239e824c83dd512ab8
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Aug 15 06:31:12 2021 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Aug 15 06:31:29 2021 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=61a55687

deprecation: Remove obsolete qa-policy.conf link

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 deprecation.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/deprecation.rst b/deprecation.rst
index 83284f5..1fb03a6 100644
--- a/deprecation.rst
+++ b/deprecation.rst
@@ -25,7 +25,6 @@ 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

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     cb43291806dac6f2a8d26f2ef4a794b42e8c52a5
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Apr 10 12:54:58 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jan 26 18:46:27 2021 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=cb432918

installed-files: Virtuals must not install any files.

Closes: https://bugs.gentoo.org/716970
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 installed-files.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/installed-files.rst b/installed-files.rst
index db949b0..da6263e 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -88,3 +88,21 @@ and caused many issues, in particular due to hardcoding full paths.
 Today they are practically replaced by more portable pkg-config files,
 and while libtool keeps generating them, they are considered
 unnecessary and potentially harmful.
+
+
+.. index::
+   pair: installed files; virtuals
+
+Virtuals
+--------
+:PG: 0304
+:Source: QA
+:Reported: no
+
+Packages in the ``virtual`` category must not install any files.
+
+*Rationale*:  The ``virtual`` category is reserved for packages with
+an empty installation image.  Package managers rely on this for some
+optimizations.  Also QA tools make certain assumptions about virtuals,
+e.g., that they must not assign the ``LICENSE`` variable (which would
+be impossible if they installed any files).

[gentoo-commits] proj/policy-guide:master commit in: /

[Ulrich Müller]

commit:     00d4bf27d309047b5a8a5bf86908a85decd637d5
Author:     Joonas Niilola <juippis <AT> gentoo <DOT> org>
AuthorDate: Mon Jan 11 12:02:45 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Jan 26 18:42:38 2021 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=00d4bf27

dependencies: update eutils.eclass into optfeature.eclass

Closes: https://github.com/gentoo/policy-guide/pull/20
Signed-off-by: Joonas Niilola <juippis <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 dependencies.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/dependencies.rst b/dependencies.rst
index a1f5177..c0afb81 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -18,8 +18,8 @@ dependencies is installed.
 
 There is no specific preference as to how user should be informed
 of optional runtime dependencies.  Three possible ways are
-``optfeature`` from ``eutils`` eclass, ``readme.gentoo-r1`` eclass
-and plain ``elog`` messages.
+``optfeature`` eclass, ``readme.gentoo-r1`` eclass and plain ``elog``
+messages.
 
 *Rationale*: toggling USE flags in order to enable or disable optional
 runtime dependencies causes needless rebuilds of packages in question.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     3f2ce4891bfdb363bbc28c615643c844e10dd0f4
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Fri Nov  6 20:45:52 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Fri Nov  6 22:24:35 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=3f2ce489

deprecation: Eclass deprecation is now indicated in eclassdoc

Closes: https://github.com/gentoo/policy-guide/pull/19
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 deprecation.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/deprecation.rst b/deprecation.rst
index c0badd0..83284f5 100644
--- a/deprecation.rst
+++ b/deprecation.rst
@@ -32,6 +32,5 @@ 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``.
+Deprecations are indicated using the ``@DEPRECATED`` eclassdoc tag
+inside the eclass files.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     2ab9dac1a436e8698963da0aa0a00c978611a747
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Sep 13 06:56:12 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Sep 13 06:56:12 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=2ab9dac1

installed-files: Fix -remove → -delete

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 installed-files.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/installed-files.rst b/installed-files.rst
index c8c55f2..db949b0 100644
--- a/installed-files.rst
+++ b/installed-files.rst
@@ -79,7 +79,7 @@ b. the package is installing static libraries that have additional
 
 It is recommended to use the following one-liner to remove .la files::
 
-    find "${ED}" -name '*.la' -remove || die
+    find "${ED}" -name '*.la' -delete || die
 
 *Rationale*: libtool files were historically introduced as an attempt
 to supplement static library archives with dependent library list.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     589aee44fc22bbdd43ddc8708d1f00cb0c990533
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Mar  2 06:51:46 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Thu Mar  5 07:59:21 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=589aee44

deprecation: Include deprecated eclasses

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/16
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 deprecation.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/deprecation.rst b/deprecation.rst
index 7264fa1..c0badd0 100644
--- a/deprecation.rst
+++ b/deprecation.rst
@@ -17,3 +17,21 @@ 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``.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     a6e07a7839514aa39abb4259d05ef5dc6fb6b7d7
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Wed Feb 26 13:32:15 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon Mar  2 05:15:24 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=a6e07a78

Cover deprecated EAPIs

While this is probably too obvious to require an explicit policy,
it makes sense to assign a PG identifier for it.

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 deprecation.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/deprecation.rst b/deprecation.rst
new file mode 100644
index 0000000..7264fa1
--- /dev/null
+++ b/deprecation.rst
@@ -0,0 +1,19 @@
+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``.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     694625737d6a7428606e3b8a2ba9330677edd96c
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Feb 23 20:44:08 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Feb 25 15:15:24 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=69462573

Copy singlehtml into html directory

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 Makefile | 5 ++++-
 tox.ini  | 2 +-
 2 files changed, 5 insertions(+), 2 deletions(-)

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/tox.ini b/tox.ini
index 987da45..faedab9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -10,4 +10,4 @@ whitelist_externals =
 	make
 
 commands =
-	make {posargs:html}
+	make {posargs:all}

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     0834171b83aead95ae39e51272a9f89bb785e28b
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Tue Feb 18 17:05:52 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Fri Feb 21 11:07:40 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=0834171b

ebuild-format: Require KEYWORDS to be on one line

Bug: https://bugs.gentoo.org/639724
Closes: https://github.com/gentoo/policy-guide/pull/13
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 ebuild-format.rst | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/ebuild-format.rst b/ebuild-format.rst
index d2c8dc5..ed9bde0 100644
--- a/ebuild-format.rst
+++ b/ebuild-format.rst
@@ -68,7 +68,6 @@ 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
 
@@ -87,3 +86,20 @@ 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
+-----------------------------------------
+: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.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     557319dfdd2e495af848d1803227941c2a4f82fd
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Tue Feb 11 10:05:58 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Fri Feb 21 11:07:33 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=557319df

other-metadata: LICENSE

Closes: https://bugs.gentoo.org/709020
Closes: https://github.com/gentoo/policy-guide/pull/12
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 other-metadata.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/other-metadata.rst b/other-metadata.rst
index f05014b..14651cf 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -94,4 +94,53 @@ this circumstance, and they will not fail for users.
    common, and there is little harm in overspecifying it.
 
 
+.. index:: license
+
+LICENSE
+-------
+: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

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     33111d2aa554f253f920d7f0b3d866a739e38f56
Author:     Max Magorsch <max <AT> magorsch <DOT> de>
AuthorDate: Sat Jan 25 22:02:40 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 26 04:39:37 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=33111d2a

Use pypi for installing the tyrian-sphinx-theme

Signed-off-by: Max Magorsch <max <AT> magorsch.de>
Closes: https://github.com/gentoo/policy-guide/pull/11
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 2261cc5..987da45 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,7 +5,7 @@ skipsdist = True
 [testenv]
 deps =
 	sphinx
-	git+https://github.com/mmagorsc/tyrian_sphinx_theme/#egg=tyrian_sphinx_theme
+	tyrian-sphinx-theme
 whitelist_externals =
 	make
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     18417ff218fb635c9be42d76187c3a979101edd8
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 22 03:13:08 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Jan 22 03:13:08 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=18417ff2

index: Display full TOC

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 index.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/index.rst b/index.rst
index c1295a6..b3bcddc 100644
--- a/index.rst
+++ b/index.rst
@@ -10,7 +10,6 @@ in which the policy can be updated.
 
 
 .. toctree::
-   :maxdepth: 2
    :caption: Contents:
    :glob:
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     5d3972de21bc06154fc3e1c6b8bb4041457e4dae
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 17:56:55 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Jan 22 03:05:29 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=5d3972de

other-metadata: meaningful homepage policy

Closes: https://bugs.gentoo.org/705866
Closes: https://github.com/gentoo/policy-guide/pull/7
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 other-metadata.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/other-metadata.rst b/other-metadata.rst
index ca3759a..61749cb 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -36,4 +36,31 @@ manager behavior which could include use of unpredictable slot, cache
 invalidation or explicit errors.
 
 
+.. index::
+   single: homepage; meaningful value
+   pair: homepage; gentoo.org
+
+HOMEPAGE value must be meaningful
+---------------------------------
+:Source: QA
+:Reference: https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035
+:Reported: known bad values are reported by pkgcheck
+
+The HOMEPAGE specified for the package should either be dedicated
+to the package in question or make it easy to find dedicated
+information.  Packages must not use ``https://www.gentoo.org/``
+or a similar generic homepage.  If no homepage is available, the special
+value of ``https://wiki.gentoo.org/wiki/No_homepage`` must be used.
+
+*Rationale*: The homepage specified in ebuilds is normally used to
+locate information about the upstream project, e.g. downloads, source
+code repository, bug tracker, documentation.  Homepages that make it
+hard to locate information about a specific project have little value,
+and the Gentoo homepage generally does not do a good job at linking even
+major Gentoo projects.  Furthermore, many of the projects did not even
+have a single dedicated subpage anywhere in Gentoo web space.  In all
+those cases, using the explicit No_homepage marker at least makes it
+easy to identify such packages.
+
+
 .. _metadata invariance: https://projects.gentoo.org/pms/7/pms.html#x1-600007.1

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     c674d07888a8b95b2f39a8bcdc7755e0b1560451
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 21:14:07 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Jan 22 03:05:44 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=c674d078

other-metadata: RESTRICT="!test? ( test )"

Closes: https://bugs.gentoo.org/705892
Closes: https://github.com/gentoo/policy-guide/pull/9
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 other-metadata.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/other-metadata.rst b/other-metadata.rst
index 61749cb..f05014b 100644
--- a/other-metadata.rst
+++ b/other-metadata.rst
@@ -63,4 +63,35 @@ those cases, using the explicit No_homepage marker at least makes it
 easy to identify such packages.
 
 
+.. index::
+   single: restrict; test; USE=-test
+   single: USE flags; test; restrict
+
+RESTRICT=test for USE=-test
+---------------------------
+:Source: QA
+:Reported: by pkgcheck
+
+Whenever the package uses ``test`` flag to control test prerequisites
+(or another flag with a similar purpose), it must explicitly restrict
+tests when the flag is unset.
+
+*Example*::
+
+    IUSE="test"
+    RESTRICT="!test? ( test )"
+
+*Rationale*: contrary to common assumption, ``test`` flag is not special
+and the package manager can execute tests when the flag is disabled.
+The explicit restriction guarantees that tests will be skipped under
+this circumstance, and they will not fail for users.
+
+.. Note::
+   Technically there are packages that do not strictly require this
+   restriction since they handle missing test prerequisites gracefully
+   (e.g. by skipping the tests).  However, we enforce the rule for all
+   packages since omitting the restriction by mistake is much more
+   common, and there is little harm in overspecifying it.
+
+
 .. _metadata invariance: https://projects.gentoo.org/pms/7/pms.html#x1-600007.1

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     0719b0f628b12a542b4e9b3327ab493c0e1daf76
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 20:29:58 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Jan 21 16:47:48 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=0719b0f6

dependencies: policy on 4-style USE deps

Closes: https://bugs.gentoo.org/705890
Closes: https://github.com/gentoo/policy-guide/pull/8
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 dependencies.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/dependencies.rst b/dependencies.rst
index 38f4147..55bba5c 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -167,5 +167,46 @@ dependencies as a result.
    if the package installed by the user still links to libfoo.
 
 
+.. index::
+   pair: USE flags; dependency
+
+USE dependencies
+----------------
+
+on packages without the flag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:Source: QA (inferred from PMS)
+:Reported: by pkgcheck
+
+Whenever a package uses a 2-style USE-dependency on another package,
+all package versions matching the dependency must have the flag
+in question.  If the dependency matches at least one version missing
+the flag, either 4-style USE-dependency (i.e. having ``(-)`` or ``(+)``
+indicator) must be used, or the restriction must be refined to match
+only versions having the flag.
+
+*Example*::
+
+    # BAD: USE=gtk2 is not supported by v2
+    dev-foo/libfrobnicate[gtk2]
+    # GOOD: all matching versions have USE=tools
+    <dev-foo/libfrobnicate-2[gtk2]
+    # GOOD: indicate the default
+    dev-foo/libfrobnicate[gtk2(-)]
+
+    # BAD: USE=tools is no longer needed with v2
+    dev-foo/libbar[tools]
+    # GOOD: indicate the default
+    dev-foo/libbar[tools(+)]
+
+*Rationale*: according to the PMS section on `2-style and 4-style USE
+dependencies`_, it is an error to apply 2-style USE dependency to
+a package missing the flag.  Furthermore, checking for this makes it
+possible to report whenever USE flags on a package are changed without
+updating its reverse dependencies.
+
+
 .. _GLEP 62: https://www.gentoo.org/glep/glep-0062.html
 .. _Paludis: https://paludis.exherbo.org/
+.. _2-style and 4-style USE dependencies:
+     https://projects.gentoo.org/pms/7/pms.html#x1-790008.2.6.4

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     e2c175ac142dd62b687107a3aff5c41908d34ca9
Author:     Joonas Niilola <juippis <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 12 07:28:48 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Tue Jan 21 16:44:47 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=e2c175ac

dependencies: include optfeature

Still used from eutils.eclass before it gets built into EAPI.

Signed-off-by: Joonas Niilola <juippis <AT> gentoo.org>
Closes: https://github.com/gentoo/policy-guide/pull/3
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 dependencies.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/dependencies.rst b/dependencies.rst
index 51038be..38f4147 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -16,8 +16,9 @@ being nonfunctional unless at least one of a set of optional runtime
 dependencies is installed.
 
 There is no specific preference as to how user should be informed
-of optional runtime dependencies.  The two possible options include
-using ``elog`` messages and ``readme.gentoo-r1`` eclass.
+of optional runtime dependencies.  Three possible ways are
+``optfeature`` from ``eutils`` eclass, ``readme.gentoo-r1`` eclass
+and plain ``elog`` messages.
 
 *Rationale*: toggling USE flags in order to enable or disable optional
 runtime dependencies causes needless rebuilds of packages in question.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     acb2659d5d3c67579105d0b297dfda4bc92edf47
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 12:39:34 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 20:09:53 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=acb2659d

filesystem: Policy against absolute symlink targets

Closes: https://bugs.gentoo.org/705830
Closes: https://github.com/gentoo/policy-guide/pull/5
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 filesystem.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/filesystem.rst b/filesystem.rst
index 9173042..081ab99 100644
--- a/filesystem.rst
+++ b/filesystem.rst
@@ -154,3 +154,29 @@ inconsistent with the use in other distributions where it was used to
 share data files.  Since the latter implied users must not be added
 to the games group, a new group (gamestat) needed to be created to
 fulfill that purpose.
+
+
+.. index:: symbolic link; absolute target
+
+Absolute symbolic link targets
+------------------------------
+:Source: QA
+:Reported: by repoman and pkgcheck (when ebuild-generated)
+
+Packages must not install symbolic links with absolute targets.
+Instead, relative paths must be used.  An exception is granted
+for symlinks to specially mounted filesystems (such as /proc, /run)
+when symlinks are supposed to always reference the running host system.
+
+*Example*::
+
+    # BAD:
+    dosym /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate
+    # GOOD:
+    dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate
+    # ACCEPTABLE EXCEPTION:
+    dosym /proc/self/mounts /etc/mtab
+
+*Rationale*: absolute symlinks work correctly only when the root
+filesystem is mounted at /.  They point at the wrong location whenever
+it is mounted in another location, e.g. for the purposes of recovery.

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     7becf8322c2e53b484faa5565df3c3fcde2be85d
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 19 13:53:05 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 20:10:03 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=7becf832

dependencies: =-deps with no revision

Closes: https://bugs.gentoo.org/705842
Closes: https://github.com/gentoo/policy-guide/pull/6
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 dependencies.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/dependencies.rst b/dependencies.rst
index ff6756f..51038be 100644
--- a/dependencies.rst
+++ b/dependencies.rst
@@ -30,6 +30,34 @@ This is especially important for packages that take long time to build.
    by the Council but no reference implementation has been written.
 
 
+.. index:: dependency; = with no revision
+
+=-dependencies with no revision
+-------------------------------
+:Source: QA
+:Reported: by repoman and pkgcheck
+
+Whenever a non-wildcard ``=`` (equals) dependency is used on a package,
+the requested revision must be specified explicitly.  When the zeroth
+revision is requested, ``-r0`` must be used.  When no specific revision
+is necessary, the ``~`` (tilde) operator must be used instead.
+
+*Example*::
+
+    # BAD:
+    =dev-libs/libfrobnicate-1.2.3
+    # GOOD:
+    =dev-libs/libfrobnicate-1.2.3-r0
+    =dev-libs/libfrobnicate-1.2.3-r3
+    ~dev-libs/libfrobnicate-1.2.3
+
+*Rationale*: using ``=`` operator in place of ``~`` to mean a specific
+version has been a common mistake.  This policy uses the fact that
+no revision and explicit ``-r0`` are equivalent.  By explicitly
+requesting the latter, it warns developers to reconsider whether they
+used the correct operator.
+
+
 .. index::
    pair: slot/subslot; dependency
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     9b0775038bb995e0ef831ea5d9c35563991f8cb4
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 11 22:35:25 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 10:51:28 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=9b077503

Add a chapter on maintainers

Closes: https://bugs.gentoo.org/705472
Closes: https://github.com/gentoo/policy-guide/pull/1
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 maintainer.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/maintainer.rst b/maintainer.rst
new file mode 100644
index 0000000..07dd3b1
--- /dev/null
+++ b/maintainer.rst
@@ -0,0 +1,73 @@
+Package Maintainers
+===================
+
+.. index:: maintainer; adding
+
+Adding new maintainers
+----------------------
+:Source: QA
+:Reported: no
+
+Developers must not add other developers as package maintainers, unless
+the developers in question consent to that.  Developers must not add
+projects that they are not members of as package maintainers, unless
+one of the project members explicitly agrees to that or the project
+policy explicitly permits it.
+
+*Rationale*: this policy aims to prevent package maintainers being added
+as backup maintainers without their consent or knowledge.  What's worse,
+once the original maintainer resigns the packages frequently drop
+to backup maintainers who are neither interested in maintaining them,
+nor often aware why they are listed as maintainers.
+
+For example, developers used to frequently add Python team as a backup
+maintainer to various packages not fitting the project's profile.  This
+includes various end-user programs written in Python.  Many of those
+packages ended up being maintained solely by Python, and distinguishing
+them from packages actually within project's profile was hard.
+
+
+.. index:: maintainer; new packages without
+
+New packages without a maintainer
+---------------------------------
+:Source: QA
+:Reported: no
+
+It is explicitly forbidden to add new packages without a dedicated
+maintainer.  This does not apply if the package in question is not
+technically a new one but merely split out of unmaintained package.
+
+*Rationale*: Gentoo is currently suffering from a very large number
+of packages without a maintainer.  There is a small group of developers
+trying to fix them as necessary.  It is unfair and inappropriate
+to increase their maintenance burden by adding new packages and refusing
+to take care of them.
+
+
+.. index:: maintainer; removing
+.. index:: up for grabs
+
+Removing package maintainers
+----------------------------
+:Source: QA
+:Reported: no
+
+When removing maintainers from a package, the developer must reassign
+all bugs filed for it.  Furthermore, when removing the last maintainer
+for a package, the developer must add the following comment
+to ``metadata.xml``::
+
+    <!-- maintainer-needed -->
+
+Furthermore, the developer must send an 'up for grabs' mail
+to gentoo-dev mailing list, containing the list of packages with
+no maintainer.  If possible, please include any information that could
+be helpful to future maintainers.
+
+*Rationale*: reassigning bugs is necessary to make sure that old bugs
+are not lost assigned to developers who are no longer interested
+in them.  The maintainer-needed comment is meant to make it possible
+to easily grep for unmaintained packages.  The 'up for grabs' mails aim
+to increase the chances of packages finding a new maintainers (compared
+to them silently becoming maintainer-needed).

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     e8c1bf40fb65daf1e90112a21296cb61e06b1fbb
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 12 07:17:58 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 10:51:33 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=e8c1bf40

Rekeywording & stabilization rules

Closes: https://bugs.gentoo.org/705474
Closes: https://github.com/gentoo/policy-guide/pull/2
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 keywords.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/keywords.rst b/keywords.rst
index 5dcbc77..272dca4 100644
--- a/keywords.rst
+++ b/keywords.rst
@@ -1,6 +1,51 @@
 Keywording and stabilization
 ============================
 
+.. index:: keywords; rekeywording
+
+Rekeywording on dropped keywords
+--------------------------------
+:Source: QA
+:Reported: by pkgcheck and repoman
+
+The developer removing keywords from a package (e.g. due to new
+dependencies) must file a rekeywording bug asking for the package being
+retested.  This rule can be exempted if the package is known not to work
+(anymore) on the arch in question.
+
+*Rationale*: rekeywording on minor architectures often takes a long
+time.  If a developer neglects to request it immediately, it negatively
+affects other developers who in the future either want to stabilize
+a new version or to remove an old version.
+
+
+.. index:: keywords; stabilizing new versions
+
+Stabilizing new versions
+------------------------
+:Source: QA
+:Reported: by pkgcheck
+
+Whenever requesting a stabilization of a new version of the package,
+the developer must CC *all* arches that had at least one previous stable
+version of the package in question, and that still have ~arch keywords
+in the stabilized version.  This applies to experimental architectures
+as well.
+
+The stabilization request can be closed and old stable version removed
+once all non-experimental architectures have processed the stabilization
+request.  However, the remaining arch teams should be kept CC-ed in case
+they wanted to process the bug.
+
+*Rationale*: there were some cases of developers requesting
+stabilization only of a subset of architectures they were personally
+interested in.  This meant some other developer had to independently
+request stabilization on remaining architectures which only meant
+a duplication of effort and unnecessary confusion over which version
+is stable and whether arch teams are slacking or stabilization was not
+requested on remaining architectures in the first place.
+
+
 .. index:: keywords; removing stable
 
 Removing stable keywords

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     81f8d870c8696e4fb37fefee9458c5caa1ebf1ad
Author:     Max Magorsch <max <AT> magorsch <DOT> de>
AuthorDate: Sat Jan 18 23:58:37 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jan 19 10:51:09 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=81f8d870

Use a Sphinx theme based on Tyrian

A Sphinx theme based on Tyrian is used. The theme is automatically
installed and applied when using tox. If you are not using tox. please
refer to the documentaion of the theme for further installation
instructions.

Signed-off-by: Max Magorsch <max <AT> magorsch.de>
Closes: https://github.com/gentoo/policy-guide/pull/4
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 conf.py | 9 +++++++--
 tox.ini | 1 +
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/conf.py b/conf.py
index 34b7273..e91b613 100644
--- a/conf.py
+++ b/conf.py
@@ -73,13 +73,18 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'tyrian_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'sidebar' : 'right',
+    'navigationlinks_top' : 'none',
+    'navigationlinks_bottom' : 'long',
+    'navigationlinks_navbar' : 'none'
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/tox.ini b/tox.ini
index 1873355..2261cc5 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,6 +5,7 @@ skipsdist = True
 [testenv]
 deps =
 	sphinx
+	git+https://github.com/mmagorsc/tyrian_sphinx_theme/#egg=tyrian_sphinx_theme
 whitelist_externals =
 	make
 

[gentoo-commits] proj/policy-guide:master commit in: /

[Michał Górny]

commit:     8120b86795a077d97b8920412500392d161d8b10
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Jan 13 19:33:06 2020 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon Jan 13 19:33:06 2020 +0000
URL:        https://gitweb.gentoo.org/proj/policy-guide.git/commit/?id=8120b867

Clean builds up

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 Makefile | 5 ++---
 tox.ini  | 4 +++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 1c9d813..5168496 100644
--- a/Makefile
+++ b/Makefile
@@ -8,10 +8,9 @@ SPHINXPROJ    = GentooPolicyGuide
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-html:
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+all: html
 
-.PHONY: html Makefile
+.PHONY: all Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

diff --git a/tox.ini b/tox.ini
index 5913c11..1873355 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,6 +5,8 @@ skipsdist = True
 [testenv]
 deps =
 	sphinx
+whitelist_externals =
+	make
 
 commands =
-	make html
+	make {posargs:html}