/[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.3 Revision 1.6
1GLEP: 46 1GLEP: 46
2Title: Allow upstream tags in metadata.xml 2Title: Allow upstream tags in metadata.xml
3Version: $Revision: 1.3 $ 3Version: $Revision: 1.6 $
4Last-Modified: $Date: 2007/04/21 03:13:16 $ 4Last-Modified: $Date: 2008/05/10 07:50:43 $
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: Deferred 6Status: Accepted
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 10Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008, 10-May-2008
11 11
12Abstract 12Abstract
13======== 13========
14 14
15Tree ``metadata.xml`` files are currently used to specify maintainer and 15Tree ``metadata.xml`` files are currently used to specify maintainer and
42 useful information to end users. 42 useful information to end users.
43 43
44* It will reduce the time spent by developers trying to find how to 44* It will reduce the time spent by developers trying to find how to
45 contact upstream. 45 contact upstream.
46 46
47* It will give treecleaners additional information to decide whether
48 a package can be removed from the tree.
49
47Specification 50Specification
48============= 51=============
49 52
50``metadata.dtd`` should allow the use of a upstream tag in 53``metadata.dtd`` should allow the use of a upstream tag in
51``metadata.xml``. Inside the upstream tag, developers should be able to 54``metadata.xml``. Inside the upstream tag, developers should be able to
52add upstream related information. 55add upstream related information.
53 56
54This GLEP defines the following four tags for ``upstream``: 57This GLEP defines the following five tags for ``upstream``:
55``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of 58``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
56which are mandatory. Future GLEPs may extend this -- tools processing 59which are mandatory. Future GLEPs may extend this -- tools processing
57metadata.xml should ignore unrecognized elements. 60metadata.xml should ignore unrecognized elements.
58 61
59``maintainer`` can contain the tags ``name`` and ``email``, indicating 62``maintainer`` can contain the tags ``name`` and ``email``, indicating
60the person or organization responsible for upstream maintainership of 63the person or organization responsible for upstream maintainership of
61the package. 64the package. The tag may appear more than once.
62 65
63``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``.
64 69
65``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.
66 74
67``changelog`` should contain a URL prefixed with ``http://`` or 75``name`` should contain a block of text with upstream's name, is mandatory
68``https://`` where the location of the upstream changelog can be found. 76and can only appear once.
69 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
81changelog can be found. The URL must be version independent and must point to
82a changelog which is only updated on new releases of the corresponding
83package. (This also implies that one can link to an automatically updated
84changelog in case of vcs snapshots only.)
85
86``doc`` should contain a URL where the location of the upstream
87documentation can be found. The link must not point to any third party
88documentation and must be version independent. If the documentation is
89available in more than one language, a ``lang`` attribute can be used
90which follows the same rules as the one for ``longdescription``.
91
70``bugs-to`` should contain a place where bugs can be filed, a URL 92``bugs-to`` should contain a place where bugs can be filed, a URL or an
71prefixed with ``http://`` or ``https://`` or an e-mail address prefixed 93e-mail address prefixed with ``mailto:``.
72with ``mailto:``.
73 94
74``remote-id`` should specify a type of package identification tracker 95``remote-id`` should specify a type of package identification tracker
75and the identification that corresponds to the package in question. 96and the identification that corresponds to the package in question.
76``remote-id`` should make it easier to index information such as its 97``remote-id`` should make it easier to index information such as its
77Freshmeat ID or its CPAN name. 98Freshmeat ID or its CPAN name.
80identifying the type of upstream source. Examples are ``freshmeat``, in 101identifying the type of upstream source. Examples are ``freshmeat``, in
81which case the element content should be the Freshmeat ID or ``vim``, in 102which case the element content should be the Freshmeat ID or ``vim``, in
82which case the element content should be the ``vim.org`` script 103which case the element content should be the ``vim.org`` script
83identifier. This GLEP does not specify a complete list of legal values 104identifier. This GLEP does not specify a complete list of legal values
84for ``type`` -- developers should email the ``gentoo-dev`` mailing list 105for ``type`` -- developers should email the ``gentoo-dev`` mailing list
85before using a new ``type`` value. 106before using a new ``type`` value. The list of valid tags should be kept
107in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``.
86 108
87For example, a ``metadata.xml`` upstream snippet may look like:: 109For example, a ``metadata.xml`` upstream snippet may look like::
88 110
89 <upstream> 111 <upstream>
90 <maintainer> 112 <maintainer status="inactive">
91 <name>Foo Bar</name> 113 <name>Foo Bar</name>
92 <email>foo@bar.bar</email> 114 <email>foo@bar.bar</email>
93 </maintainer> 115 </maintainer>
116 <maintainer status="active">
117 <name>Foo Gentoo</name>
118 <email>foo@gentoo.org</email>
119 </maintainer>
94 <changelog>http://foo.bar/changelog.txt</changelog> 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>
95 <bugs-to>https://bugs.foo.bar</bugs-to> 123 <bugs-to>https://bugs.foo.bar</bugs-to>
96 <remote-id type="freshmeat">12345</remote-id> 124 <remote-id type="freshmeat">foobar</remote-id>
97 <remote-id type="sourceforge">foobar</remote-id> 125 <remote-id type="sourceforge">foobar</remote-id>
98 </upstream> 126 </upstream>
99 127
100 128
101Backwards Compatibility 129Backwards Compatibility
102======================= 130=======================
103 131
104No changes are necessary to existing ``metadata.xml`` files. Information 132No changes are necessary to existing ``metadata.xml`` files. Information
105in the new tags is not be mandatory. Any sane tool that currently 133in the new tags is not mandatory. Tools that currently read
106handles ``metadata.xml`` files will simply ignore unrecognised elements. 134``metadata.xml`` files may break if written poorly; well written tools
135should just ignore the additional elements.
136
137Notes
138=====
139
140The specified URLs must include a protocol as described in RFC 3986.
141Furthermore the most common protocol should be used in case of several
142possibilities (http should be favoured over https or ftp over gopher or svn,
143etc).
144
107 145
108Copyright 146Copyright
109========= 147=========
110 148
111This document has been placed in the public domain. 149This document has been placed in the public domain.

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

  ViewVC Help
Powered by ViewVC 1.1.20