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

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

  ViewVC Help
Powered by ViewVC 1.1.20