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='<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='>=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 |