/[gentoo]/xml/htdocs/proj/en/glep/glep-0046.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0046.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20