diff options
Diffstat (limited to '_sources/motivation.rst.txt')
| -rw-r--r-- | _sources/motivation.rst.txt | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/_sources/motivation.rst.txt b/_sources/motivation.rst.txt new file mode 100644 index 0000000..46ce064 --- /dev/null +++ b/_sources/motivation.rst.txt @@ -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/ |