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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (show annotations) (download) (as text)
Thu Jan 24 13:00:09 2008 UTC (6 years, 2 months ago) by dev-zero
Branch: MAIN
Changes since 1.6: +37 -13 lines
File MIME type: text/html
Updated glep-0046 according to the discussion on the gentoo.devel mailinglist

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">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
5 <head>
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8 <title>GLEP 46 -- Allow upstream tags in metadata.xml</title>
9 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10 </head>
11 <body bgcolor="white">
12 <table class="navigation" cellpadding="0" cellspacing="0"
13 width="100%" border="0">
14 <tr><td class="navicon" width="150" height="35">
15 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17 border="0" width="150" height="35" /></a></td>
18 <td class="textlinks" align="left">
19 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0046.txt">GLEP Source</a></b>]
22 </td></tr></table>
23 <table class="rfc2822 docutils field-list" frame="void" rules="none">
24 <col class="field-name" />
25 <col class="field-body" />
26 <tbody valign="top">
27 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">46</td>
28 </tr>
29 <tr class="field"><th class="field-name">Title:</th><td class="field-body">Allow upstream tags in metadata.xml</td>
30 </tr>
31 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
32 </tr>
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">2007/04/21 03:13:16</a></td>
34 </tr>
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>
36 </tr>
37 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Deferred</td>
38 </tr>
39 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40 </tr>
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>
42 </tr>
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</td>
46 </tr>
47 </tbody>
48 </table>
49 <hr />
50 <div class="contents topic">
51 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52 <ul class="simple">
53 <li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
54 <li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
55 <li><a class="reference" href="#specification" id="id4" name="id4">Specification</a></li>
56 <li><a class="reference" href="#backwards-compatibility" id="id5" name="id5">Backwards Compatibility</a></li>
57 <li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li>
58 </ul>
59 </div>
60 <div class="section">
61 <h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
62 <p>Tree <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files are currently used to specify maintainer and
63 description information for packages. This GLEP proposes extensions to
64 <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> to allow storage of information about upstream.</p>
65 </div>
66 <div class="section">
67 <h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
68 <p>The range of upstream-related data currently available to developers and
69 tool 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
70 ebuilds.</p>
71 <p>There have been several attempts at creating tools that check a
72 package's versions against Freshmeat to see whether an ebuild version
73 bump is required. Currently identifying a package's Freshmeat entry is a
74 matter of guesswork, and not something that can reliably be automated.</p>
75 <p>Similarly, various scripts exist to check a package's status against a
76 specialist external data source. One of the authors, for example, has a
77 shell script hack that tries to determine whether any <tt class="docutils literal"><span class="pre">app-vim</span></tt>
78 packages need bumping by checking the associated <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
79 page. Again, tying packages to external data source entries is not
80 particulaly straight forward.</p>
81 <p>Making additional upstream-related data easily available will have other
82 benefits:</p>
83 <ul class="simple">
84 <li>It will allow systems such as the Packages website to provide more
85 useful information to end users.</li>
86 <li>It will reduce the time spent by developers trying to find how to
87 contact upstream.</li>
88 <li>It will give treecleaners additional information to decide whether
89 a package can be removed from the tree.</li>
90 </ul>
91 </div>
92 <div class="section">
93 <h1><a class="toc-backref" href="#id4" id="specification" name="specification">Specification</a></h1>
94 <p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in
95 <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Inside the upstream tag, developers should be able to
96 add upstream related information.</p>
97 <p>This GLEP defines the following five tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
98 <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
99 which are mandatory. Future GLEPs may extend this -- tools processing
100 metadata.xml should ignore unrecognized elements.</p>
101 <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
102 the person or organization responsible for upstream maintainership of
103 the package. The tag may appear more than once.</p>
104 <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
105 <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
106 shall be interpreted as <tt class="docutils literal"><span class="pre">unknown</span></tt>.</p>
107 <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>
108 element in cases where a developer decides to maintain the package in
109 addition to/instead of the original upstream. In such cases a <tt class="docutils literal"><span class="pre">maintainer</span></tt>
110 entry for the original upstream should be present.</p>
111 <p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name, is mandatory
112 and can only appear once.</p>
113 <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>
114 <p><tt class="docutils literal"><span class="pre">changelog</span></tt> should contain a URL prefixed with <tt class="docutils literal"><span class="pre">http://</span></tt> or
115 <tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream changelog can be found.</p>
116 <p><tt class="docutils literal"><span class="pre">doc</span></tt> should contain a URL prefixed with with <tt class="docutils literal"><span class="pre">http://</span></tt> or
117 <tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream documentation can be found.
118 The link must not point to any third party documentation and must be version
119 independent. If the documentation is available in more than one language, a
120 <tt class="docutils literal"><span class="pre">lang</span></tt> attribute can be used which follows the same rules as the one
121 for <tt class="docutils literal"><span class="pre">longdescription</span></tt>.</p>
122 <p><tt class="docutils literal"><span class="pre">bugs-to</span></tt> should contain a place where bugs can be filed, a URL
123 prefixed with <tt class="docutils literal"><span class="pre">http://</span></tt> or <tt class="docutils literal"><span class="pre">https://</span></tt> or an e-mail address prefixed
124 with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
125 <p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker
126 and the identification that corresponds to the package in question.
127 <tt class="docutils literal"><span class="pre">remote-id</span></tt> should make it easier to index information such as its
128 Freshmeat ID or its CPAN name.</p>
129 <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
130 identifying the type of upstream source. Examples are <tt class="docutils literal"><span class="pre">freshmeat</span></tt>, in
131 which case the element content should be the Freshmeat ID or <tt class="docutils literal"><span class="pre">vim</span></tt>, in
132 which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
133 identifier. This GLEP does not specify a complete list of legal values
134 for <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
135 before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value. The list of valid tags should be kept
136 in <tt class="docutils literal"><span class="pre">metadata/dtd/remote-id-tags.dtd</span></tt>.</p>
137 <p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
138 <pre class="literal-block">
139 &lt;upstream&gt;
140 &lt;maintainer status=&quot;inactive&quot;&gt;
141 &lt;name&gt;Foo Bar&lt;/name&gt;
142 &lt;email&gt;foo&#64;bar.bar&lt;/email&gt;
143 &lt;/maintainer&gt;
144 &lt;maintainer status=&quot;active&quot;&gt;
145 &lt;name&gt;Foo Gentoo&lt;/name&gt;
146 &lt;email&gt;foo&#64;gentoo.org&lt;/email&gt;
147 &lt;/maintainer&gt;
148 &lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt;
149 &lt;doc lang=&quot;en&quot;&gt;http://foo.bar/doc/index.html&lt;/doc&gt;
150 &lt;doc lang=&quot;de&quot;&gt;http://foo.bar./doc/index.de.html&lt;/doc&gt;
151 &lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt;
152 &lt;remote-id type=&quot;freshmeat&quot;&gt;foobar&lt;/remote-id&gt;
153 &lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt;
154 &lt;/upstream&gt;
155 </pre>
156 </div>
157 <div class="section">
158 <h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
159 <p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
160 in the new tags is not mandatory. Tools that currently read
161 <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files may break if written poorly; well written tools
162 should just ignore the additional elements.</p>
163 </div>
164 <div class="section">
165 <h1><a class="toc-backref" href="#id6" id="copyright" name="copyright">Copyright</a></h1>
166 <p>This document has been placed in the public domain.</p>
167 <!-- vim: set ft=glep tw=72 : -->
168 </div>
169
170 </div>
171 <div class="footer">
172 <hr class="footer" />
173 <a class="reference" href="glep-0046.txt">View document source</a>.
174 Generated on: 2008-01-24 12:57 UTC.
175 Generated 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.
176
177 </div>
178 </body>
179 </html>

  ViewVC Help
Powered by ViewVC 1.1.20