diff options
authorMichał Górny <>2020-01-08 08:58:34 +0100
committerMichał Górny <>2020-01-08 09:47:39 +0100
commit90b611f2fbb851c528610780a16805b6182e166e (patch)
Initial version
Signed-off-by: Michał Górny <>
7 files changed, 397 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ba65b13
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..1c9d813
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+# You can set these variables from the command line.
+SPHINXBUILD = sphinx-build
+SPHINXPROJ = GentooPolicyGuide
+BUILDDIR = _build
+.PHONY: html Makefile
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
diff --git a/basics.rst b/basics.rst
new file mode 100644
index 0000000..c29b902
--- /dev/null
+++ b/basics.rst
@@ -0,0 +1,72 @@
+Basic information
+Goals of policy making
+The Gentoo policies focus on three aims:
+1. *Portability*. By following the policies, it should be possible
+ to package software so that it works on different system setups.
+ This includes various supported architectures, basic system
+ components, service managers, package managers, combinations
+ of compiler and linker flags, etc.
+2. *Maintainability*. The policies aim to provide consistent coding
+ practices that make it easy for a different person to co-maintain
+ the package or take over after previous maintainer. This also
+ reduces the risk of mistakes experienced by the end users.
+3. *End-user experience*. The policies try to help developers
+ in providing a consistent end-user experience. The same concepts
+ applied across different packages make it easier for user to achieve
+ his goals and reduce the likeliness of surprising behavior.
+Policy compliance checking
+Currently, there are two kinds of tools involved in detecting policy
+1. Linting-class tools, including repoman_ and pkgcheck_. Those tools
+ analyze ebuilds and other files in the package repository for known
+ policy violations. They are limited to checking for problems that
+ can be detected without running the phase functions.
+2. Build- and install-time QA checks, implemented in package managers.
+ Those trigger while the ebuilds are executing. They are limited
+ to testing the currently running code path.
+Developers are expected to use both kinds of tools before pushing their
+commits. They should both lint the changed ebuilds using repoman_
+or pkgcheck_, and test whether their packages build and install
+Additionally, Gentoo is running pkgcheck_ periodically as `Gentoo CI`_.
+All non-trivial violations are reported to the gentoo-automated-testing_
+mailing list and to the developers making the relevant commits. This
+supplements the direct use of linting tools by developers with reliable
+tree-wide scans.
+Policy enforcement
+The Gentoo `QA team`_ is tasked with enforcement of the tree policies.
+Its role is governed by `GLEP 48`_. It focuses on documenting
+the policies, resolving doubts regarding them and educating
+the developers.
+The QA team members can also take direct action in resolving minor
+quality problems (i.e. when fixing directly involves far less effort
+than if the developer was requested to fix it), or when developer
+refuses to resolve policy violations.
+Finally, in case of repeated unwillingness to follow policies, the QA
+team can issue disciplinary measures against the developer in question.
+.. _repoman:
+.. _pkgcheck:
+.. _Gentoo CI:
+.. _gentoo-automated-testing:
+.. _QA team:
+.. _GLEP 48:
diff --git a/ b/
new file mode 100644
index 0000000..25ec69e
--- /dev/null
+++ b/
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# -- Path setup --------------------------------------------------------------
+# 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('.'))
+# -- Project information -----------------------------------------------------
+project = 'Gentoo Policy Guide'
+copyright = '2020, Gentoo Authors'
+author = 'Michał Górny'
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+# -- General configuration ---------------------------------------------------
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+# The master toctree document.
+master_doc = 'index'
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# 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
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+# -- Options for HTML output -------------------------------------------------
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'alabaster'
+# 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 = {}
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself. Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+# html_sidebars = {}
+# -- Options for HTMLHelp output ---------------------------------------------
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'GentooPolicyGuidedoc'
+# -- Options for LaTeX output ------------------------------------------------
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'GentooPolicyGuide.tex', 'Gentoo Policy Guide Documentation',
+ 'Michał Górny', 'manual'),
+# -- Options for manual page output ------------------------------------------
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'gentoopolicyguide', 'Gentoo Policy Guide Documentation',
+ [author], 1)
+# -- Options for Texinfo output ----------------------------------------------
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'GentooPolicyGuide', 'Gentoo Policy Guide Documentation',
+ author, 'GentooPolicyGuide', 'One line description of project.',
+ 'Miscellaneous'),
diff --git a/index.rst b/index.rst
new file mode 100644
index 0000000..aca80e4
--- /dev/null
+++ b/index.rst
@@ -0,0 +1,27 @@
+Gentoo Policy Guide
+Gentoo Policy Guide aims to become a definitive clear source of all
+Tree Policies that are currently binding to Gentoo developers.
+It combines both policies that are global by design (i.e. set by the QA
+team or the Council), as well as specific to other Gentoo projects.
+The policies are meant to be supplied with rationale and clear
+indication of the body setting the policy, and therefore the process
+in which the policy can be updated.
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :glob:
+ motivation
+ basics
+ other-docs
+ *
+Indices and tables
+* :ref:`genindex`
+* :ref:`search`
diff --git a/motivation.rst b/motivation.rst
new file mode 100644
index 0000000..46ce064
--- /dev/null
+++ b/motivation.rst
@@ -0,0 +1,59 @@
+Motivation and history
+Historical state of policy documentation
+At the time, Gentoo was lacking a clear and focused document listing all
+development-related policies in a concise and clear way.
+PMS_ provided a technical specification for the ebuild files but did
+not provide a sufficient explanation on how to use it. Furthermore, PMS
+was focused on wider usage of the ebuild files than intended for
+the Gentoo repository, and therefore was partially restricted via tree
+Past Council decisions can be found in the `Council meeting logs`_.
+However, their form makes it hard to find any particular decision,
+not to mention establishing a complete list of policies.
+At some point, the QA team started listing `QA policies`_ on its wiki
+page. Only eight policies were listed so far. The policies were written
+out as a flat list with no particular order which is not going to scale
+Finally, there was an attempt to turn devmanual_ into a source of
+reference policies. It was rejected by its maintainers as explicitly
+against the original purpose of this document. Furthermore, a large
+amount of stale information combined with ability to edit by every
+developer would make it unclear which parts are applicable policies,
+and which are obsolete or non-binding tips.
+There are also project policies, scattered across wiki pages and other
+project documentation, and a lot of de facto policies that were
+established less or more formally in the past but were never really
+written down.
+Purpose of the Policy Guide
+The Policy Guide was created in order to address aforementioned
+documentation deficiencies. Its primary purpose is to collect all
+applicable policies from various sources and combine them into a single
+logically organized document.
+Along with a wording of each policy, its rationale should be provided
+(if available) and an indication of which body set the policy.
+The former should make it possible to better understand the policy,
+and apply it in spirit rather than requiring very precise wording.
+The latter should make it clear who can be queried for additional
+information, and how the policy can be updated if need arises.
+This Guide is going to replace the QA team policies page. All new QA
+policies will be documented directly in it. Other documentation (e.g.
+devmanual) should conform to policies stated here.
+.. _PMS:
+.. _Council meeting logs:
+.. _QA policies:
+.. _devmanual:
diff --git a/other-docs.rst b/other-docs.rst
new file mode 100644
index 0000000..fc28bd7
--- /dev/null
+++ b/other-docs.rst
@@ -0,0 +1,65 @@
+Other policy documents
+Gentoo-specific documentation
+Package Manager Specification
+PMS_ provides the specification of ebuild format, as well as general
+guidelines for implementing package managers. All ebuilds in the Gentoo
+repository are required to conform to the PMS. Tree policies may
+enforce additional restrictions upon the format discussed in PMS.
+PMS is maintained by the `PMS project`_. All major changes are done
+in subsequent EAPIs that are approved by the Council. The project's
+wiki page discusses how PMS can be changed via `future EAPI process`_.
+GLEPs_ provide the highest level policies applicable to Gentoo. Final
+or active GLEPs apply to all developers. Tree policies may impose
+additional restrictions on GLEPs but may not override them.
+The process for creating and updating GLEPs is documented in `GLEP 1`_.
+In general, all GLEP updates go through mailing list review and need
+to be approved by the Council.
+Developer Manual
+Devmanual_ is the basic guide for ebuild developers. Besides policies,
+it contains many general recommendations and detailed instructions.
+Developer Manual does not specify policies itself, and needs to comply
+with policies defined in this document.
+Technically, devmanual can be changed by any developer. However, it is
+recommended that all changes are reviewed by the `devmanual project`_.
+External standards
+POSIX_ is the basic standard for operating systems. However, its rules
+apply to the software packaged in Gentoo rather than the distribution
+itself. Nevertheless, when no more specific policy applies, following
+POSIX is recommended.
+FHS_ specifies the suggested filesystem layout for Linux systems.
+Gentoo follows FHS only partially. Whenever Gentoo policies and FHS
+disagree, Gentoo policies should be followed.
+.. _PMS:
+.. _PMS project:
+.. _future EAPI process:
+.. _GLEPs:
+.. _GLEP 1:
+.. _devmanual:
+.. _devmanual project:
+.. _POSIX:
+.. _FHS: