This adds a new '<notes/>' element to allow maintainers to describe
package-specific quirks or other instructions on how to correctly
maintain a package. This is intended to encourage developers to document
knowledge and increase the bus-factor of packages which are delicate
but must live beyond a maintainer.
Signed-off-by: Sam James <s...@gentoo.org>
---
glep-0068.rst | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/glep-0068.rst b/glep-0068.rst
index 83e54d9..21bdf2a 100644
--- a/glep-0068.rst
+++ b/glep-0068.rst
@@ -4,10 +4,10 @@ Title: Package and category metadata
Author: Michał Górny <mgo...@gentoo.org>
Type: Standards Track
Status: Final
-Version: 1.1
+Version: 1.2
Created: 2016-03-14
-Last-Modified: 2021-09-11
-Post-History: 2016-03-16, 2018-02-20
+Last-Modified: 2021-10-05
+Post-History: 2016-03-16, 2018-02-20, 2021-10-05
Content-Type: text/x-rst
Requires: 67
Replaces: 34, 46, 56
@@ -160,6 +160,8 @@ element can contain, in any order:
in different languages (at most one for each language), as detailed
in `USE flag descriptions`_.
+- at most one ``<notes/>`` element containing notes on maintenance.
+
- at most one ``<upstream/>`` element providing information on upstream
of the package, as detailed in `Upstream descriptions`_.
@@ -213,6 +215,18 @@ The ``<use/>`` element can contain the following elements:
which the description applies, and contains text, optionally interspersed
with ``<cat/>`` and ``<pkg/>`` elements.
+Notes element
+~~~~~~~~~~~~~
+
+The ``<notes/>`` element describes important information on how to maintain
+a package.
+
+The ``<notes/>`` element has an obligatory ``type=""`` attribute whose value is
+can be either ``text`` or ``url``. If its value is ``text``, then the
+``<notes/>`` value is formed of multi-line text. If its value is ``url``, the
+``<notes/>`` value should be a link to a page containing information on how
+to correct maintain the package.
+
Upstream descriptions
~~~~~~~~~~~~~~~~~~~~~
The ``<upstream/>`` element provides information on the upstream of a package.
@@ -484,6 +498,12 @@ Example metadata.xml file
<flag name='bar' restrict='<dev-libs/foo-12'>Konfiguriert das Paket
mit Unterstützung für bar (benötigt <pkg>dev-libs/bar</pkg>)</flag>
<flag name='bar' restrict='>=dev-libs/foo-12'>Konfiguriert das
Paket mit Unterstützung für bar</flag>
</use>
+ <notes type="text">
+ Almost every release involves checking a diff of the build system.
+ Be careful of bundled libfoo which sometimes has custom
modifications.
+ Versioning scheme is unusual.
+ Track record of ABI breaks within minor releases: check!
+ </notes>
<upstream>
<maintainer status='active'>
<email>upstr...@example.com</email>
--
2.33.0
