1 |
GLEP: 46 |
2 |
Title: Allow upstream tags in metadata.xml |
3 |
Version: $Revision: 1.4 $ |
4 |
Last-Modified: $Date: 2008/01/24 13:00:09 $ |
5 |
Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org> |
6 |
Status: Deferred |
7 |
Type: Standards Track |
8 |
Content-Type: text/x-rst |
9 |
Created: 26-Dec-2005 |
10 |
Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008 |
11 |
|
12 |
Abstract |
13 |
======== |
14 |
|
15 |
Tree ``metadata.xml`` files are currently used to specify maintainer and |
16 |
description information for packages. This GLEP proposes extensions to |
17 |
``metadata.xml`` to allow storage of information about upstream. |
18 |
|
19 |
Motivation |
20 |
========== |
21 |
|
22 |
The range of upstream-related data currently available to developers and |
23 |
tool authors is currently limited to ``DESCRIPTION`` and ``HOMEPAGE`` in |
24 |
ebuilds. |
25 |
|
26 |
There have been several attempts at creating tools that check a |
27 |
package's versions against Freshmeat to see whether an ebuild version |
28 |
bump is required. Currently identifying a package's Freshmeat entry is a |
29 |
matter of guesswork, and not something that can reliably be automated. |
30 |
|
31 |
Similarly, various scripts exist to check a package's status against a |
32 |
specialist external data source. One of the authors, for example, has a |
33 |
shell script hack that tries to determine whether any ``app-vim`` |
34 |
packages need bumping by checking the associated ``vim.org`` script |
35 |
page. Again, tying packages to external data source entries is not |
36 |
particulaly straight forward. |
37 |
|
38 |
Making additional upstream-related data easily available will have other |
39 |
benefits: |
40 |
|
41 |
* It will allow systems such as the Packages website to provide more |
42 |
useful information to end users. |
43 |
|
44 |
* It will reduce the time spent by developers trying to find how to |
45 |
contact upstream. |
46 |
|
47 |
* It will give treecleaners additional information to decide whether |
48 |
a package can be removed from the tree. |
49 |
|
50 |
Specification |
51 |
============= |
52 |
|
53 |
``metadata.dtd`` should allow the use of a upstream tag in |
54 |
``metadata.xml``. Inside the upstream tag, developers should be able to |
55 |
add upstream related information. |
56 |
|
57 |
This GLEP defines the following five tags for ``upstream``: |
58 |
``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of |
59 |
which are mandatory. Future GLEPs may extend this -- tools processing |
60 |
metadata.xml should ignore unrecognized elements. |
61 |
|
62 |
``maintainer`` can contain the tags ``name`` and ``email``, indicating |
63 |
the person or organization responsible for upstream maintainership of |
64 |
the package. The tag may appear more than once. |
65 |
|
66 |
The ``maintainer`` element has a ``status`` attribute, which is one of |
67 |
``active`` or ``inactive``. This attribute is not mandatory. The absence of it |
68 |
shall be interpreted as ``unknown``. |
69 |
|
70 |
The ``maintainer`` element can be the same as the top-level ``maintainer`` |
71 |
element in cases where a developer decides to maintain the package in |
72 |
addition to/instead of the original upstream. In such cases a ``maintainer`` |
73 |
entry for the original upstream should be present. |
74 |
|
75 |
``name`` should contain a block of text with upstream's name, is mandatory |
76 |
and can only appear once. |
77 |
|
78 |
``email`` should contain an e-mail address in the format ``foo@bar.bar``. |
79 |
|
80 |
``changelog`` should contain a URL where the location of the upstream |
81 |
changelog can be found. The URL must be version independent and must point to |
82 |
a changelog which is only updated on new releases of the corresponding |
83 |
package. (This also implies that one can link to an automatically updated |
84 |
changelog in case of vcs snapshots only.) |
85 |
|
86 |
``doc`` should contain a URL where the location of the upstream |
87 |
documentation can be found. The link must not point to any third party |
88 |
documentation and must be version independent. If the documentation is |
89 |
available in more than one language, a ``lang`` attribute can be used |
90 |
which follows the same rules as the one for ``longdescription``. |
91 |
|
92 |
``bugs-to`` should contain a place where bugs can be filed, a URL or an |
93 |
e-mail address prefixed with ``mailto:``. |
94 |
|
95 |
``remote-id`` should specify a type of package identification tracker |
96 |
and the identification that corresponds to the package in question. |
97 |
``remote-id`` should make it easier to index information such as its |
98 |
Freshmeat ID or its CPAN name. |
99 |
|
100 |
The ``remote-id`` element has a ``type`` attribute, which is a string |
101 |
identifying the type of upstream source. Examples are ``freshmeat``, in |
102 |
which case the element content should be the Freshmeat ID or ``vim``, in |
103 |
which case the element content should be the ``vim.org`` script |
104 |
identifier. This GLEP does not specify a complete list of legal values |
105 |
for ``type`` -- developers should email the ``gentoo-dev`` mailing list |
106 |
before using a new ``type`` value. The list of valid tags should be kept |
107 |
in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``. |
108 |
|
109 |
For example, a ``metadata.xml`` upstream snippet may look like:: |
110 |
|
111 |
<upstream> |
112 |
<maintainer status="inactive"> |
113 |
<name>Foo Bar</name> |
114 |
<email>foo@bar.bar</email> |
115 |
</maintainer> |
116 |
<maintainer status="active"> |
117 |
<name>Foo Gentoo</name> |
118 |
<email>foo@gentoo.org</email> |
119 |
</maintainer> |
120 |
<changelog>http://foo.bar/changelog.txt</changelog> |
121 |
<doc lang="en">http://foo.bar/doc/index.html</doc> |
122 |
<doc lang="de">http://foo.bar/doc/index.de.html</doc> |
123 |
<bugs-to>https://bugs.foo.bar</bugs-to> |
124 |
<remote-id type="freshmeat">foobar</remote-id> |
125 |
<remote-id type="sourceforge">foobar</remote-id> |
126 |
</upstream> |
127 |
|
128 |
|
129 |
Backwards Compatibility |
130 |
======================= |
131 |
|
132 |
No changes are necessary to existing ``metadata.xml`` files. Information |
133 |
in the new tags is not mandatory. Tools that currently read |
134 |
``metadata.xml`` files may break if written poorly; well written tools |
135 |
should just ignore the additional elements. |
136 |
|
137 |
Notes |
138 |
===== |
139 |
|
140 |
The specified URLs must include a protocol as described in RFC 3986. |
141 |
Furthermore the most common protocol should be used in case of several |
142 |
possibilities (http should be favoured over https or ftp over gopher or svn, |
143 |
etc). |
144 |
|
145 |
|
146 |
Copyright |
147 |
========= |
148 |
|
149 |
This document has been placed in the public domain. |
150 |
|
151 |
.. vim: set ft=glep tw=72 : |
152 |
|