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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.10 - (hide annotations) (download) (as text)
Sat May 10 07:52:46 2008 UTC (10 years, 10 months ago) by dev-zero
Branch: MAIN
Changes since 1.9: +5 -5 lines
File MIME type: text/html
Set state to Accepted as per Gentoo Council Meeting 20080410

1 ciaranm 1.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 antarus 1.6
5 ciaranm 1.1 <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 ciaranm 1.2 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8 ciaranm 1.1 <title>GLEP 46 -- Allow upstream tags in metadata.xml</title>
9 antarus 1.6 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10 ciaranm 1.1 </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 antarus 1.6 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 ciaranm 1.2 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0046.txt">GLEP Source</a></b>]
22 ciaranm 1.1 </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 dev-zero 1.10 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.6</td>
32 ciaranm 1.1 </tr>
33 dev-zero 1.10 <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>
34 ciaranm 1.1 </tr>
35 dev-zero 1.7 <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 ciaranm 1.1 </tr>
37 dev-zero 1.10 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Accepted</td>
38 ciaranm 1.1 </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </tr>
41 ciaranm 1.2 <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 ciaranm 1.1 </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td>
44     </tr>
45 dev-zero 1.10 <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>
46 ciaranm 1.2 </tr>
47 ciaranm 1.1 </tbody>
48     </table>
49     <hr />
50 ciaranm 1.2 <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52 ciaranm 1.1 <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 dev-zero 1.9 <li><a class="reference" href="#notes" id="id6" name="id6">Notes</a></li>
58     <li><a class="reference" href="#copyright" id="id7" name="id7">Copyright</a></li>
59 ciaranm 1.1 </ul>
60     </div>
61 ciaranm 1.2 <div class="section">
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
64     description information for packages. This GLEP proposes extensions to
65     <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> to allow storage of information about upstream.</p>
66     </div>
67     <div class="section">
68     <h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
69     <p>The range of upstream-related data currently available to developers and
70     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
71     ebuilds.</p>
72     <p>There have been several attempts at creating tools that check a
73     package's versions against Freshmeat to see whether an ebuild version
74     bump is required. Currently identifying a package's Freshmeat entry is a
75     matter 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
77     specialist external data source. One of the authors, for example, has a
78     shell script hack that tries to determine whether any <tt class="docutils literal"><span class="pre">app-vim</span></tt>
79     packages need bumping by checking the associated <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
80     page. Again, tying packages to external data source entries is not
81     particulaly straight forward.</p>
82     <p>Making additional upstream-related data easily available will have other
83     benefits:</p>
84     <ul class="simple">
85     <li>It will allow systems such as the Packages website to provide more
86     useful information to end users.</li>
87     <li>It will reduce the time spent by developers trying to find how to
88     contact upstream.</li>
89 dev-zero 1.7 <li>It will give treecleaners additional information to decide whether
90     a package can be removed from the tree.</li>
91 ciaranm 1.2 </ul>
92     </div>
93     <div class="section">
94     <h1><a class="toc-backref" href="#id4" id="specification" name="specification">Specification</a></h1>
95     <p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in
96     <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Inside the upstream tag, developers should be able to
97     add upstream related information.</p>
98 dev-zero 1.7 <p>This GLEP defines the following five tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
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
100 ciaranm 1.2 which are mandatory. Future GLEPs may extend this -- tools processing
101     metadata.xml should ignore unrecognized elements.</p>
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
103     the person or organization responsible for upstream maintainership of
104 dev-zero 1.7 the 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
107     shall 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>
109     element in cases where a developer decides to maintain the package in
110     addition to/instead of the original upstream. In such cases a <tt class="docutils literal"><span class="pre">maintainer</span></tt>
111     entry for the original upstream should be present.</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
113     and can only appear once.</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>
115 dev-zero 1.9 <p><tt class="docutils literal"><span class="pre">changelog</span></tt> should contain a URL where the location of the upstream
116     changelog can be found. The URL must be version independent and must point to
117     a changelog which is only updated on new releases of the corresponding
118     package. (This also implies that one can link to an automatically updated
119     changelog 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
121     documentation can be found. The link must not point to any third party
122     documentation and must be version independent. If the documentation is
123     available in more than one language, a <tt class="docutils literal"><span class="pre">lang</span></tt> attribute can be used
124     which follows the same rules as the one for <tt class="docutils literal"><span class="pre">longdescription</span></tt>.</p>
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
126     e-mail address prefixed with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
127 ciaranm 1.2 <p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker
128     and the identification that corresponds to the package in question.
129     <tt class="docutils literal"><span class="pre">remote-id</span></tt> should make it easier to index information such as its
130     Freshmeat ID or its CPAN name.</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
132     identifying the type of upstream source. Examples are <tt class="docutils literal"><span class="pre">freshmeat</span></tt>, in
133     which case the element content should be the Freshmeat ID or <tt class="docutils literal"><span class="pre">vim</span></tt>, in
134     which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
135     identifier. This GLEP does not specify a complete list of legal values
136     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
137 dev-zero 1.7 before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value. The list of valid tags should be kept
138 dev-zero 1.9 in <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 ciaranm 1.2 <p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
140 ciaranm 1.1 <pre class="literal-block">
141     &lt;upstream&gt;
142 dev-zero 1.7 &lt;maintainer status=&quot;inactive&quot;&gt;
143 ciaranm 1.2 &lt;name&gt;Foo Bar&lt;/name&gt;
144     &lt;email&gt;foo&#64;bar.bar&lt;/email&gt;
145     &lt;/maintainer&gt;
146 dev-zero 1.7 &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;
150 ciaranm 1.2 &lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt;
151 dev-zero 1.7 &lt;doc lang=&quot;en&quot;&gt;http://foo.bar/doc/index.html&lt;/doc&gt;
152 dev-zero 1.9 &lt;doc lang=&quot;de&quot;&gt;http://foo.bar/doc/index.de.html&lt;/doc&gt;
153 ciaranm 1.2 &lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt;
154 dev-zero 1.7 &lt;remote-id type=&quot;freshmeat&quot;&gt;foobar&lt;/remote-id&gt;
155 ciaranm 1.2 &lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt;
156 ciaranm 1.1 &lt;/upstream&gt;
157     </pre>
158     </div>
159 ciaranm 1.2 <div class="section">
160     <h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
161     <p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
162 dev-zero 1.7 in 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
164     should just ignore the additional elements.</p>
165 ciaranm 1.1 </div>
166 ciaranm 1.2 <div class="section">
167 dev-zero 1.9 <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>.
169     Furthermore the most common protocol should be used in case of several
170     possibilities (http should be favoured over https or ftp over gopher or svn,
171     etc).</p>
172     </div>
173     <div class="section">
174     <h1><a class="toc-backref" href="#id7" id="copyright" name="copyright">Copyright</a></h1>
175 ciaranm 1.1 <p>This document has been placed in the public domain.</p>
176 ciaranm 1.2 <!-- vim: set ft=glep tw=72 : -->
177 ciaranm 1.1 </div>
179     </div>
180     <div class="footer">
181     <hr class="footer" />
182     <a class="reference" href="glep-0046.txt">View document source</a>.
183 dev-zero 1.10 Generated on: 2008-05-10 07:51 UTC.
184 ciaranm 1.1 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.
186     </div>
187     </body>
188     </html>

  ViewVC Help
Powered by ViewVC 1.1.20