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

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

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

Revision 1.1 Revision 1.10
1<?xml version="1.0" encoding="utf-8" ?> 1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<!-- 4
5This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8-->
9<head> 5<head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" /> 7 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 <title>GLEP 46 -- Allow upstream tags in metadata.xml</title> 8 <title>GLEP 46 -- Allow upstream tags in metadata.xml</title>
13 <link rel="stylesheet" href="tools/glep.css" type="text/css" /> 9 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
14</head> 10</head>
15<body bgcolor="white"> 11<body bgcolor="white">
16<table class="navigation" cellpadding="0" cellspacing="0" 12<table class="navigation" cellpadding="0" cellspacing="0"
… …
20<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]" 16<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21 border="0" width="150" height="35" /></a></td> 17 border="0" width="150" height="35" /></a></td>
22<td class="textlinks" align="left"> 18<td class="textlinks" align="left">
23[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>] 19[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>] 20[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
25[<b><a href="./glep-0046.txt">GLEP Source</a></b>] 21[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0046.txt">GLEP Source</a></b>]
26</td></tr></table> 22</td></tr></table>
27<table class="rfc2822 docutils field-list" frame="void" rules="none"> 23<table class="rfc2822 docutils field-list" frame="void" rules="none">
28<col class="field-name" /> 24<col class="field-name" />
29<col class="field-body" /> 25<col class="field-body" />
30<tbody valign="top"> 26<tbody valign="top">
31<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">46</td> 27<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">46</td>
32</tr> 28</tr>
33<tr class="field"><th class="field-name">Title:</th><td class="field-body">Allow upstream tags in metadata.xml</td> 29<tr class="field"><th class="field-name">Title:</th><td class="field-body">Allow upstream tags in metadata.xml</td>
34</tr> 30</tr>
35<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.0</td> 31<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.6</td>
36</tr> 32</tr>
37<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs/xml/htdocs/proj/en/glep/glep-0046.txt?cvsroot=gentoo">2005/12/26 20:00:00</a></td> 33<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0046.txt?cvsroot=gentoo">2008/05/10 07:50:43</a></td>
38</tr> 34</tr>
39<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcelo Goes &lt;vanquirius&#32;&#97;t&#32;gentoo.org&gt;, Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;</td> 35<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcelo Goes &lt;vanquirius&#32;&#97;t&#32;gentoo.org&gt;, Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;, Tiziano Müller &lt;dev-zero&#32;&#97;t&#32;gentoo.org&gt;</td>
40</tr> 36</tr>
41<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> 37<tr class="field"><th class="field-name">Status:</th><td class="field-body">Accepted</td>
42</tr> 38</tr>
43<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> 39<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
44</tr> 40</tr>
45<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="http://www.python.org/peps/glep-0012.html">text/x-rst</a></td> 41<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
46</tr> 42</tr>
47<tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td> 43<tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td>
44</tr>
45<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Dec-2005, 5-Mar-2006, 24-Jan-2008, 10-May-2008</td>
48</tr> 46</tr>
49</tbody> 47</tbody>
50</table> 48</table>
51<hr /> 49<hr />
52<div class="contents topic" id="contents"> 50<div class="contents topic">
53<p class="topic-title first"><a name="contents">Contents</a></p> 51<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
54<ul class="simple"> 52<ul class="simple">
55<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li> 53<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
56<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li> 54<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
57<li><a class="reference" href="#specification" id="id4" name="id4">Specification</a></li> 55<li><a class="reference" href="#specification" id="id4" name="id4">Specification</a></li>
58<li><a class="reference" href="#backwards-compatibility" id="id5" name="id5">Backwards Compatibility</a></li> 56<li><a class="reference" href="#backwards-compatibility" id="id5" name="id5">Backwards Compatibility</a></li>
57<li><a class="reference" href="#notes" id="id6" name="id6">Notes</a></li>
59<li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li> 58<li><a class="reference" href="#copyright" id="id7" name="id7">Copyright</a></li>
60</ul> 59</ul>
61</div> 60</div>
62<div class="section" id="abstract"> 61<div class="section">
63<h1><a class="toc-backref" href="#id2" name="abstract">Abstract</a></h1> 62<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
63<p>Tree <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files are currently used to specify maintainer and
64description information for packages. This GLEP proposes extensions to
64<p><tt class="docutils literal"><span class="pre">metadata.xml</span></tt> should allow the use of tags to add information related to 65<tt class="docutils literal"><span class="pre">metadata.xml</span></tt> to allow storage of information about upstream.</p>
65upstream, such as who the upstream maintainers are, the upstream changelog and
66where to report bugs.</p>
67</div> 66</div>
68<div class="section" id="motivation"> 67<div class="section">
69<h1><a class="toc-backref" href="#id3" name="motivation">Motivation</a></h1> 68<h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
70<p>Allowing developers to add upstream information in <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> will make it 69<p>The range of upstream-related data currently available to developers and
71easier, faster and more reliable to share it with other developers. Having 70tool authors is currently limited to <tt class="docutils literal"><span class="pre">DESCRIPTION</span></tt> and <tt class="docutils literal"><span class="pre">HOMEPAGE</span></tt> in
72information from upstream should avoid duplicated work in tasks such as browsing 71ebuilds.</p>
73upstream's Homepage and mailing lists.</p> 72<p>There have been several attempts at creating tools that check a
73package's versions against Freshmeat to see whether an ebuild version
74bump is required. Currently identifying a package's Freshmeat entry is a
75matter of guesswork, and not something that can reliably be automated.</p>
76<p>Similarly, various scripts exist to check a package's status against a
77specialist external data source. One of the authors, for example, has a
78shell script hack that tries to determine whether any <tt class="docutils literal"><span class="pre">app-vim</span></tt>
79packages need bumping by checking the associated <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
80page. Again, tying packages to external data source entries is not
81particulaly straight forward.</p>
82<p>Making additional upstream-related data easily available will have other
83benefits:</p>
84<ul class="simple">
85<li>It will allow systems such as the Packages website to provide more
86useful information to end users.</li>
87<li>It will reduce the time spent by developers trying to find how to
88contact upstream.</li>
89<li>It will give treecleaners additional information to decide whether
90a package can be removed from the tree.</li>
91</ul>
74</div> 92</div>
75<div class="section" id="specification"> 93<div class="section">
76<h1><a class="toc-backref" href="#id4" name="specification">Specification</a></h1> 94<h1><a class="toc-backref" href="#id4" id="specification" name="specification">Specification</a></h1>
77<p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. 95<p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in
78Inside the upstream tag, developers should be able to add upstream information 96<tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Inside the upstream tag, developers should be able to
79in the tags named <tt class="docutils literal"><span class="pre">maintainer,</span> <span class="pre">``changelog</span></tt>, <tt class="docutils literal"><span class="pre">bugs-to</span></tt> and <tt class="docutils literal"><span class="pre">remote-id</span></tt>.</p> 97add upstream related information.</p>
80<p>This GLEP defines the following four tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>: 98<p>This GLEP defines the following five tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
81<tt class="docutils literal"><span class="pre">maintainer</span></tt>, <tt class="docutils literal"><span class="pre">changelog</span></tt>, <tt class="docutils literal"><span class="pre">bugs-to</span></tt> and <tt class="docutils literal"><span class="pre">remote-id</span></tt>, none of which are 99<tt class="docutils literal"><span class="pre">maintainer</span></tt>, <tt class="docutils literal"><span class="pre">changelog</span></tt>, <tt class="docutils literal"><span class="pre">bugs-to</span></tt>, <tt class="docutils literal"><span class="pre">remote-id</span></tt> and <tt class="docutils literal"><span class="pre">doc</span></tt> none of
82mandatory. Future GLEPs may extend this -- tools processing metadata.xml should 100which are mandatory. Future GLEPs may extend this -- tools processing
83ignore unrecognized elements.</p> 101metadata.xml should ignore unrecognized elements.</p>
84<p><tt class="docutils literal"><span class="pre">maintainer</span></tt> can contain the tags <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">email</span></tt>, indicating the 102<p><tt class="docutils literal"><span class="pre">maintainer</span></tt> can contain the tags <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">email</span></tt>, indicating
85person/organization responsible for upstream maintainership of the package.</p> 103the person or organization responsible for upstream maintainership of
104the package. The tag may appear more than once.</p>
105<p>The <tt class="docutils literal"><span class="pre">maintainer</span></tt> element has a <tt class="docutils literal"><span class="pre">status</span></tt> attribute, which is one of
106<tt class="docutils literal"><span class="pre">active</span></tt> or <tt class="docutils literal"><span class="pre">inactive</span></tt>. This attribute is not mandatory. The absence of it
107shall be interpreted as <tt class="docutils literal"><span class="pre">unknown</span></tt>.</p>
108<p>The <tt class="docutils literal"><span class="pre">maintainer</span></tt> element can be the same as the top-level <tt class="docutils literal"><span class="pre">maintainer</span></tt>
109element in cases where a developer decides to maintain the package in
110addition to/instead of the original upstream. In such cases a <tt class="docutils literal"><span class="pre">maintainer</span></tt>
111entry for the original upstream should be present.</p>
86<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name.</p> 112<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name, is mandatory
113and can only appear once.</p>
87<p><tt class="docutils literal"><span class="pre">email</span></tt> should contain an e-mail address in the format <a class="reference" href="mailto:foo&#64;bar.bar">foo&#64;bar.bar</a>.</p> 114<p><tt class="docutils literal"><span class="pre">email</span></tt> should contain an e-mail address in the format <tt class="docutils literal"><span class="pre">foo&#64;bar.bar</span></tt>.</p>
88<p><tt class="docutils literal"><span class="pre">changelog</span></tt> should contain a URL prefixed with http or https where the 115<p><tt class="docutils literal"><span class="pre">changelog</span></tt> should contain a URL where the location of the upstream
89location of the upstream changelog can be found.</p> 116changelog can be found. The URL must be version independent and must point to
117a changelog which is only updated on new releases of the corresponding
118package. (This also implies that one can link to an automatically updated
119changelog in case of vcs snapshots only.)</p>
120<p><tt class="docutils literal"><span class="pre">doc</span></tt> should contain a URL where the location of the upstream
121documentation can be found. The link must not point to any third party
122documentation and must be version independent. If the documentation is
123available in more than one language, a <tt class="docutils literal"><span class="pre">lang</span></tt> attribute can be used
124which follows the same rules as the one for <tt class="docutils literal"><span class="pre">longdescription</span></tt>.</p>
90<p><tt class="docutils literal"><span class="pre">bugs-to</span></tt> should contain a place where bugs can be filed, a URL prefixed with 125<p><tt class="docutils literal"><span class="pre">bugs-to</span></tt> should contain a place where bugs can be filed, a URL or an
91http or https or an e-mail address.</p> 126e-mail address prefixed with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
92<p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker and the 127<p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker
93identification that corresponds to the package in question. <tt class="docutils literal"><span class="pre">remote-id</span></tt> should 128and the identification that corresponds to the package in question.
94make it easier to index information like its identification in freshmeat or its 129<tt class="docutils literal"><span class="pre">remote-id</span></tt> should make it easier to index information such as its
95cpan identification.</p> 130Freshmeat ID or its CPAN name.</p>
96<p>For example:</p> 131<p>The <tt class="docutils literal"><span class="pre">remote-id</span></tt> element has a <tt class="docutils literal"><span class="pre">type</span></tt> attribute, which is a string
132identifying the type of upstream source. Examples are <tt class="docutils literal"><span class="pre">freshmeat</span></tt>, in
133which case the element content should be the Freshmeat ID or <tt class="docutils literal"><span class="pre">vim</span></tt>, in
134which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
135identifier. This GLEP does not specify a complete list of legal values
136for <tt class="docutils literal"><span class="pre">type</span></tt> -- developers should email the <tt class="docutils literal"><span class="pre">gentoo-dev</span></tt> mailing list
137before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value. The list of valid tags should be kept
138in <tt class="docutils literal"><span class="pre">metadata/dtd/remote-id-tags.dtd</span></tt> or <tt class="docutils literal"><span class="pre">metadata/dtd/metadata.dtd</span></tt>.</p>
139<p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
97<pre class="literal-block"> 140<pre class="literal-block">
98&lt;upstream&gt; 141&lt;upstream&gt;
99&lt;maintainer&gt; 142 &lt;maintainer status=&quot;inactive&quot;&gt;
100&lt;name&gt;Foo Bar&lt;/name&gt; 143 &lt;name&gt;Foo Bar&lt;/name&gt;
101&lt;email&gt;foo&#64;bar.bar&lt;/email&gt; 144 &lt;email&gt;foo&#64;bar.bar&lt;/email&gt;
102&lt;/maintainer&gt; 145 &lt;/maintainer&gt;
146 &lt;maintainer status=&quot;active&quot;&gt;
147 &lt;name&gt;Foo Gentoo&lt;/name&gt;
148 &lt;email&gt;foo&#64;gentoo.org&lt;/email&gt;
149 &lt;/maintainer&gt;
103&lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt; 150 &lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt;
151 &lt;doc lang=&quot;en&quot;&gt;http://foo.bar/doc/index.html&lt;/doc&gt;
152 &lt;doc lang=&quot;de&quot;&gt;http://foo.bar/doc/index.de.html&lt;/doc&gt;
104&lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt; 153 &lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt;
105&lt;remote-id type=&quot;freshmeat&quot;&gt;12345&lt;/remote-id&gt; 154 &lt;remote-id type=&quot;freshmeat&quot;&gt;foobar&lt;/remote-id&gt;
106&lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt; 155 &lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt;
107&lt;/upstream&gt; 156&lt;/upstream&gt;
108</pre> 157</pre>
109</div> 158</div>
110<div class="section" id="backwards-compatibility"> 159<div class="section">
111<h1><a class="toc-backref" href="#id5" name="backwards-compatibility">Backwards Compatibility</a></h1> 160<h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
112<p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Information in the new 161<p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
113tags should not be mandatory.</p> 162in the new tags is not mandatory. Tools that currently read
163<tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files may break if written poorly; well written tools
164should just ignore the additional elements.</p>
114</div> 165</div>
115<div class="section" id="copyright"> 166<div class="section">
167<h1><a class="toc-backref" href="#id6" id="notes" name="notes">Notes</a></h1>
168<p>The specified URLs must include a protocol as described in <a class="reference" href="http://www.faqs.org/rfcs/rfc3986.html">RFC 3986</a>.
169Furthermore the most common protocol should be used in case of several
170possibilities (http should be favoured over https or ftp over gopher or svn,
171etc).</p>
172</div>
173<div class="section">
116<h1><a class="toc-backref" href="#id6" name="copyright">Copyright</a></h1> 174<h1><a class="toc-backref" href="#id7" id="copyright" name="copyright">Copyright</a></h1>
117<p>This document has been placed in the public domain.</p> 175<p>This document has been placed in the public domain.</p>
176<!-- vim: set ft=glep tw=72 : -->
118</div> 177</div>
119 178
120</div> 179</div>
121<div class="footer"> 180<div class="footer">
122<hr class="footer" /> 181<hr class="footer" />
123<a class="reference" href="glep-0046.txt">View document source</a>. 182<a class="reference" href="glep-0046.txt">View document source</a>.
124Generated on: 2005-12-27 00:24 UTC. 183Generated on: 2008-05-10 07:51 UTC.
125Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. 184Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
126 185
127</div> 186</div>
128</body> 187</body>
129</html> 188</html>
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.10
  ViewVC Help
Powered by ViewVC 1.1.13