Initial version

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

1 files changed, 72 insertions, 0 deletions

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