Gentoo Archives: gentoo-dev

From: Sam James <sam@g.o>
To: gentoo-dev@l.g.o
Cc: glep@g.o, Sam James <sam@g.o>
Subject: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions
Date: Tue, 05 Oct 2021 18:28:47
Message-Id: 20211005182739.2902646-2-sam@gentoo.org
In Reply to: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68) by Sam James
1 This adds a new '<notes/>' element to allow maintainers to describe
2 package-specific quirks or other instructions on how to correctly
3 maintain a package. This is intended to encourage developers to document
4 knowledge and increase the bus-factor of packages which are delicate
5 but must live beyond a maintainer.
6
7 Signed-off-by: Sam James <sam@g.o>
8 ---
9 glep-0068.rst | 26 +++++++++++++++++++++++---
10 1 file changed, 23 insertions(+), 3 deletions(-)
11
12 diff --git a/glep-0068.rst b/glep-0068.rst
13 index 83e54d9..21bdf2a 100644
14 --- a/glep-0068.rst
15 +++ b/glep-0068.rst
16 @@ -4,10 +4,10 @@ Title: Package and category metadata
17 Author: Michał Górny <mgorny@g.o>
18 Type: Standards Track
19 Status: Final
20 -Version: 1.1
21 +Version: 1.2
22 Created: 2016-03-14
23 -Last-Modified: 2021-09-11
24 -Post-History: 2016-03-16, 2018-02-20
25 +Last-Modified: 2021-10-05
26 +Post-History: 2016-03-16, 2018-02-20, 2021-10-05
27 Content-Type: text/x-rst
28 Requires: 67
29 Replaces: 34, 46, 56
30 @@ -160,6 +160,8 @@ element can contain, in any order:
31 in different languages (at most one for each language), as detailed
32 in `USE flag descriptions`_.
33
34 +- at most one ``<notes/>`` element containing notes on maintenance.
35 +
36 - at most one ``<upstream/>`` element providing information on upstream
37 of the package, as detailed in `Upstream descriptions`_.
38
39 @@ -213,6 +215,18 @@ The ``<use/>`` element can contain the following elements:
40 which the description applies, and contains text, optionally interspersed
41 with ``<cat/>`` and ``<pkg/>`` elements.
42
43 +Notes element
44 +~~~~~~~~~~~~~
45 +
46 +The ``<notes/>`` element describes important information on how to maintain
47 +a package.
48 +
49 +The ``<notes/>`` element has an obligatory ``type=""`` attribute whose value is
50 +can be either ``text`` or ``url``. If its value is ``text``, then the
51 +``<notes/>`` value is formed of multi-line text. If its value is ``url``, the
52 +``<notes/>`` value should be a link to a page containing information on how
53 +to correct maintain the package.
54 +
55 Upstream descriptions
56 ~~~~~~~~~~~~~~~~~~~~~
57 The ``<upstream/>`` element provides information on the upstream of a package.
58 @@ -484,6 +498,12 @@ Example metadata.xml file
59 <flag name='bar' restrict='&lt;dev-libs/foo-12'>Konfiguriert das Paket mit Unterstützung für bar (benötigt <pkg>dev-libs/bar</pkg>)</flag>
60 <flag name='bar' restrict='&gt;=dev-libs/foo-12'>Konfiguriert das Paket mit Unterstützung für bar</flag>
61 </use>
62 + <notes type="text">
63 + Almost every release involves checking a diff of the build system.
64 + Be careful of bundled libfoo which sometimes has custom modifications.
65 + Versioning scheme is unusual.
66 + Track record of ABI breaks within minor releases: check!
67 + </notes>
68 <upstream>
69 <maintainer status='active'>
70 <email>upstream@×××××××.com</email>
71 --
72 2.33.0

Replies