diff options
author | 2020-01-08 08:58:34 +0100 | |
---|---|---|
committer | 2020-01-08 09:47:39 +0100 | |
commit | 90b611f2fbb851c528610780a16805b6182e166e (patch) | |
tree | ddf70dc09700b93543a4cf6aee5f3c1ce778800c | |
download | policy-guide-90b611f2fbb851c528610780a16805b6182e166e.tar.gz policy-guide-90b611f2fbb851c528610780a16805b6182e166e.tar.bz2 policy-guide-90b611f2fbb851c528610780a16805b6182e166e.zip |
Initial version
Signed-off-by: Michał Górny <mgorny@gentoo.org>
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Makefile | 19 | ||||
-rw-r--r-- | basics.rst | 72 | ||||
-rw-r--r-- | conf.py | 154 | ||||
-rw-r--r-- | index.rst | 27 | ||||
-rw-r--r-- | motivation.rst | 59 | ||||
-rw-r--r-- | other-docs.rst | 65 |
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 @@ -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 |