/[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.2 Revision 1.4
1GLEP: 46 1GLEP: 46
2Title: Allow upstream tags in metadata.xml 2Title: Allow upstream tags in metadata.xml
3Version: $Revision: 1.2 $ 3Version: $Revision: 1.4 $
4Last-Modified: $Date: 2006/03/06 03:17:07 $ 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 10Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-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
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.
74
75``name`` should contain a block of text with upstream's name, is mandatory
76and can only appear once.
77
65``email`` should contain an e-mail address in the format foo@bar.bar. 78``email`` should contain an e-mail address in the format ``foo@bar.bar``.
66 79
67``changelog`` should contain a URL prefixed with ``http://`` or 80``changelog`` should contain a URL prefixed with ``http://`` or
68``https://`` where the location of the upstream changelog can be found. 81``https://`` where the location of the upstream changelog can be found.
82
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``.
69 89
70``bugs-to`` should contain a place where bugs can be filed, a URL 90``bugs-to`` should contain a place where bugs can be filed, a URL
71prefixed with ``http://`` or ``https://`` or an e-mail address prefixed 91prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
72with ``mailto:``. 92with ``mailto:``.
73 93
80identifying the type of upstream source. Examples are ``freshmeat``, in 100identifying the type of upstream source. Examples are ``freshmeat``, in
81which case the element content should be the Freshmeat ID or ``vim``, in 101which case the element content should be the Freshmeat ID or ``vim``, in
82which case the element content should be the ``vim.org`` script 102which case the element content should be the ``vim.org`` script
83identifier. This GLEP does not specify a complete list of legal values 103identifier. This GLEP does not specify a complete list of legal values
84for ``type`` -- developers should email the ``gentoo-dev`` mailing list 104for ``type`` -- developers should email the ``gentoo-dev`` mailing list
85before using a new ``type`` value. 105before using a new ``type`` value. The list of valid tags should be kept
106in ``metadata/dtd/remote-id-tags.dtd``.
86 107
87For example, a ``metadata.xml`` upstream snippet may look like:: 108For example, a ``metadata.xml`` upstream snippet may look like::
88 109
89 <upstream> 110 <upstream>
90 <maintainer> 111 <maintainer status="inactive">
91 <name>Foo Bar</name> 112 <name>Foo Bar</name>
92 <email>foo@bar.bar</email> 113 <email>foo@bar.bar</email>
93 </maintainer> 114 </maintainer>
115 <maintainer status="active">
116 <name>Foo Gentoo</name>
117 <email>foo@gentoo.org</email>
118 </maintainer>
94 <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>
95 <bugs-to>https://bugs.foo.bar</bugs-to> 122 <bugs-to>https://bugs.foo.bar</bugs-to>
96 <remote-id type="freshmeat">12345</remote-id> 123 <remote-id type="freshmeat">foobar</remote-id>
97 <remote-id type="sourceforge">foobar</remote-id> 124 <remote-id type="sourceforge">foobar</remote-id>
98 </upstream> 125 </upstream>
99 126
100 127
101Backwards Compatibility 128Backwards Compatibility
102======================= 129=======================
103 130
104No changes are necessary to existing ``metadata.xml`` files. Information 131No changes are necessary to existing ``metadata.xml`` files. Information
105in the new tags is not be mandatory. Any sane tool that currently 132in the new tags is not mandatory. Tools that currently read
106handles ``metadata.xml`` files will simply ignore unrecognised elements. 133``metadata.xml`` files may break if written poorly; well written tools
134should just ignore the additional elements.
107 135
108Copyright 136Copyright
109========= 137=========
110 138
111This document has been placed in the public domain. 139This document has been placed in the public domain.

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

  ViewVC Help
Powered by ViewVC 1.1.20