1 |
GLEP: 46 |
2 |
Title: Allow upstream tags in metadata.xml |
3 |
Version: $Revision: 1.1 $ |
4 |
Last-Modified: $Date: 2005/12/27 00:26:58 $ |
5 |
Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org> |
6 |
Status: Draft |
7 |
Type: Standards Track |
8 |
Content-Type: text/x-rst |
9 |
Created: 26-Dec-2005 |
10 |
Post-History: 26-Dec-2005, 5-Mar-2006 |
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 |
Specification |
48 |
============= |
49 |
|
50 |
``metadata.dtd`` should allow the use of a upstream tag in |
51 |
``metadata.xml``. Inside the upstream tag, developers should be able to |
52 |
add upstream related information. |
53 |
|
54 |
This GLEP defines the following four tags for ``upstream``: |
55 |
``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of |
56 |
which are mandatory. Future GLEPs may extend this -- tools processing |
57 |
metadata.xml should ignore unrecognized elements. |
58 |
|
59 |
``maintainer`` can contain the tags ``name`` and ``email``, indicating |
60 |
the person or organization responsible for upstream maintainership of |
61 |
the package. |
62 |
|
63 |
``name`` should contain a block of text with upstream's name. |
64 |
|
65 |
``email`` should contain an e-mail address in the format foo@bar.bar. |
66 |
|
67 |
``changelog`` should contain a URL prefixed with ``http://`` or |
68 |
``https://`` where the location of the upstream changelog can be found. |
69 |
|
70 |
``bugs-to`` should contain a place where bugs can be filed, a URL |
71 |
prefixed with ``http://`` or ``https://`` or an e-mail address prefixed |
72 |
with ``mailto:``. |
73 |
|
74 |
``remote-id`` should specify a type of package identification tracker |
75 |
and the identification that corresponds to the package in question. |
76 |
``remote-id`` should make it easier to index information such as its |
77 |
Freshmeat ID or its CPAN name. |
78 |
|
79 |
The ``remote-id`` element has a ``type`` attribute, which is a string |
80 |
identifying the type of upstream source. Examples are ``freshmeat``, in |
81 |
which case the element content should be the Freshmeat ID or ``vim``, in |
82 |
which case the element content should be the ``vim.org`` script |
83 |
identifier. This GLEP does not specify a complete list of legal values |
84 |
for ``type`` -- developers should email the ``gentoo-dev`` mailing list |
85 |
before using a new ``type`` value. |
86 |
|
87 |
For example, a ``metadata.xml`` upstream snippet may look like:: |
88 |
|
89 |
<upstream> |
90 |
<maintainer> |
91 |
<name>Foo Bar</name> |
92 |
<email>foo@bar.bar</email> |
93 |
</maintainer> |
94 |
<changelog>http://foo.bar/changelog.txt</changelog> |
95 |
<bugs-to>https://bugs.foo.bar</bugs-to> |
96 |
<remote-id type="freshmeat">12345</remote-id> |
97 |
<remote-id type="sourceforge">foobar</remote-id> |
98 |
</upstream> |
99 |
|
100 |
|
101 |
Backwards Compatibility |
102 |
======================= |
103 |
|
104 |
No changes are necessary to existing ``metadata.xml`` files. Information |
105 |
in the new tags is not be mandatory. Any sane tool that currently |
106 |
handles ``metadata.xml`` files will simply ignore unrecognised elements. |
107 |
|
108 |
Copyright |
109 |
========= |
110 |
|
111 |
This document has been placed in the public domain. |
112 |
|
113 |
.. vim: set ft=glep tw=72 : |
114 |
|