Initial version

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

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 @@
+/_build/
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.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = GentooPolicyGuide
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+html:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
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
+violations:
+
+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
+correctly.
+
+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: https://wiki.gentoo.org/wiki/Repoman
+.. _pkgcheck: https://github.com/pkgcore/pkgcheck
+.. _Gentoo CI: https://qa-reports.gentoo.org/output/gentoo-ci/output.html
+.. _gentoo-automated-testing: https://archives.gentoo.org/gentoo-automated-testing/
+.. _QA team: https://wiki.gentoo.org/wiki/Project:Quality_Assurance
+.. _GLEP 48: https://www.gentoo.org/glep/glep-0048.html
diff --git a/conf.py b/conf.py
new file mode 100644
index 0000000..25ec69e
--- /dev/null
+++ b/conf.py
@@ -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:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- 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
+policies.
+
+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
+well.
+
+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: https://projects.gentoo.org/pms/latest/pms.html
+.. _Council meeting logs: https://wiki.gentoo.org/wiki/Project:Council/Meeting_logs
+.. _QA policies: https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies
+.. _devmanual: https://devmanual.gentoo.org/
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
+~~~~~
+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
+~~~~~
+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
+~~~
+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: https://projects.gentoo.org/pms/latest/pms.html
+.. _PMS project: https://wiki.gentoo.org/wiki/Project:PMS
+.. _future EAPI process: https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification/Future_EAPI_process
+.. _GLEPs: https://www.gentoo.org/glep/
+.. _GLEP 1: https://www.gentoo.org/glep/glep-0001.html
+.. _devmanual: https://devmanual.gentoo.org/
+.. _devmanual project: https://wiki.gentoo.org/wiki/Project:Devmanual
+.. _POSIX: http://get.posixcertified.ieee.org/
+.. _FHS: https://refspecs.linuxfoundation.org/fhs.shtml