commit: 57ba0f67f138341373555447371bd125e34e5b1c Author: Sam James <sam <AT> gentoo <DOT> org> AuthorDate: Mon Jan 10 01:20:35 2022 +0000 Commit: Sam James <sam <AT> gentoo <DOT> org> CommitDate: Tue Feb 22 07:11:24 2022 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=57ba0f67
ebuild-writing/eapi: document upgrade path policy The "upgrade path" policy is not particularly well-defined; over the years, various people have come to understand it as "two years", "one year", with mixed interpretations within that (is it enough to be able to upgrade just Portage?) This is a start towards formalising policy here, even if we end up changing it later, at least it's codified. Closes: https://bugs.gentoo.org/821553 Signed-off-by: Sam James <sam <AT> gentoo.org> ebuild-writing/eapi/text.xml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index e85a3ec..257232c 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -62,8 +62,29 @@ EAPI-conditional code) When writing new ebuilds developers can choose whatever EAPI they think is the best. Using the features of the latest EAPI is encouraged. </p> +</body> + +<subsection> +<title>Upgrade path</title> +<body> + +<p> +Gentoo policy is to support upgrades for installations at least a year old +with no/little intervention and up to two years old with minor intervention. To +achieve this, developers must avoid using the latest EAPI in ebuilds within +the <c>@system</c> set (see <uri link="::general-concepts/dependencies/#implicit-system-dependency"/>) +or its dependencies. +</p> + +<p> +The Base System project has +<uri link="https://wiki.gentoo.org/wiki/Project:Base#Rules_and_limitations";>rules</uri> +governing their use of newer EAPIs, as does the +<uri link="https://dev.gentoo.org/~mgorny/python-guide/package-maintenance.html#porting-packages-to-a-new-eapi";>Python project</uri>. +</p> </body> +</subsection> </section> <section>
