en/glep/glep-0046.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
  <title>GLEP 46 -- Allow upstream tags in metadata.xml</title>
  <style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2007/01/25 03:26:26 $
:version: $Revision: 1.4 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the PEP HTML output of Docutils.
*/

.first {
  margin-top: 0 }

.last {
  margin-bottom: 0 }

.navigation {
  width: 100% ;
  background: #cc99ff ;
  margin-top: 0px ;
  margin-bottom: 0px }

.navigation .navicon {
  width: 150px ;
  height: 35px }

.navigation .textlinks {
  padding-left: 1em ;
  text-align: left }

.navigation td, .navigation th {
  padding-left: 0em ;
  padding-right: 0em ;
  vertical-align: middle }

.rfc2822 {
  margin-top: 0.5em ;
  margin-left: 0.5em ;
  margin-right: 0.5em ;
  margin-bottom: 0em }

.rfc2822 td {
  text-align: left }

.rfc2822 th.field-name {
  text-align: right ;
  font-family: sans-serif ;
  padding-right: 0.5em ;
  font-weight: bold ;
  margin-bottom: 0em }

a.toc-backref {
  text-decoration: none ;
  color: black }

body {
  margin: 0px ;
  margin-bottom: 1em ;
  padding: 0px }

dd {
  margin-bottom: 0.5em }

div.section {
  margin-left: 1em ;
  margin-right: 1em ;
  margin-bottom: 1.5em }

div.section div.section {
  margin-left: 0em ;
  margin-right: 0em ;
  margin-top: 1.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.footer {
  margin-left: 1em ;
  margin-right: 1em }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1 {
  font-family: sans-serif ;
  font-size: large }

h2 {
  font-family: sans-serif ;
  font-size: medium }

h3 {
  font-family: sans-serif ;
  font-size: small }

h4 {
  font-family: sans-serif ;
  font-style: italic ;
  font-size: small }

h5 {
  font-family: sans-serif;
  font-size: x-small }

h6 {
  font-family: sans-serif;
  font-style: italic ;
  font-size: x-small }

.section hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.topic-title {
  font-family: sans-serif ;
  font-weight: bold }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

td.num {
  text-align: right }

th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0046.txt">GLEP Source</a></b>]
</td></tr></table>
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">46</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Allow upstream tags in metadata.xml</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
</tr>
<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">2006/03/06 03:17:07</a></td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Deferred</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Dec-2005, 5-Mar-2006</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
<li><a class="reference" href="#specification" id="id4" name="id4">Specification</a></li>
<li><a class="reference" href="#backwards-compatibility" id="id5" name="id5">Backwards Compatibility</a></li>
<li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
<p>Tree <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files are currently used to specify maintainer and
description information for packages. This GLEP proposes extensions to
<tt class="docutils literal"><span class="pre">metadata.xml</span></tt> to allow storage of information about upstream.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
<p>The range of upstream-related data currently available to developers and
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
ebuilds.</p>
<p>There have been several attempts at creating tools that check a
package's versions against Freshmeat to see whether an ebuild version
bump is required. Currently identifying a package's Freshmeat entry is a
matter of guesswork, and not something that can reliably be automated.</p>
<p>Similarly, various scripts exist to check a package's status against a
specialist external data source. One of the authors, for example, has a
shell script hack that tries to determine whether any <tt class="docutils literal"><span class="pre">app-vim</span></tt>
packages need bumping by checking the associated <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
page. Again, tying packages to external data source entries is not
particulaly straight forward.</p>
<p>Making additional upstream-related data easily available will have other
benefits:</p>
<ul class="simple">
<li>It will allow systems such as the Packages website to provide more
useful information to end users.</li>
<li>It will reduce the time spent by developers trying to find how to
contact upstream.</li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="specification" name="specification">Specification</a></h1>
<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>.  Inside the upstream tag, developers should be able to
add upstream related information.</p>
<p>This GLEP defines the following four tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
<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 mandatory. Future GLEPs may extend this -- tools processing
metadata.xml should ignore unrecognized elements.</p>
<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 person or organization responsible for upstream maintainership of
the package.</p>
<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name.</p>
<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>
<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
<tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream changelog can be found.</p>
<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 <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
with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker
and the identification that corresponds to the package in question.
<tt class="docutils literal"><span class="pre">remote-id</span></tt> should make it easier to index information such as its
Freshmeat ID or its CPAN name.</p>
<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
identifying the type of upstream source. Examples are <tt class="docutils literal"><span class="pre">freshmeat</span></tt>, in
which case the element content should be the Freshmeat ID or <tt class="docutils literal"><span class="pre">vim</span></tt>, in
which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
identifier. This GLEP does not specify a complete list of legal values
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
before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value.</p>
<p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
<pre class="literal-block">
&lt;upstream&gt;
        &lt;maintainer&gt;
                &lt;name&gt;Foo Bar&lt;/name&gt;
                &lt;email&gt;foo&#64;bar.bar&lt;/email&gt;
        &lt;/maintainer&gt;
        &lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt;
        &lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt;
        &lt;remote-id type=&quot;freshmeat&quot;&gt;12345&lt;/remote-id&gt;
        &lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt;
&lt;/upstream&gt;
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
<p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
in the new tags is not be mandatory. Any sane tool that currently
handles <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files will simply ignore unrecognised elements.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id6" id="copyright" name="copyright">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
<!-- vim: set ft=glep tw=72 : -->
</div>

</div>
<div class="footer">
<hr class="footer" />
<a class="reference" href="glep-0046.txt">View document source</a>.
Generated on: 2006-10-10 20:23 UTC.
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.

</div>
</body>
</html>

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	This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6	PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7	to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8	-->
9	<head>
10	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11	<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12	<title>GLEP 46 -- Allow upstream tags in metadata.xml</title>
13	<style type="text/css">
14
15	/*
16	:Author: David Goodger
17	:Contact: goodger@users.sourceforge.net
18	:date: $Date: 2007/01/25 03:26:26 $
19	:version: $Revision: 1.4 $
20	:copyright: This stylesheet has been placed in the public domain.
21
22	Default cascading style sheet for the PEP HTML output of Docutils.
23	*/
24
25	.first {
26	margin-top: 0 }
27
28	.last {
29	margin-bottom: 0 }
30
31	.navigation {
32	width: 100% ;
33	background: #cc99ff ;
34	margin-top: 0px ;
35	margin-bottom: 0px }
36
37	.navigation .navicon {
38	width: 150px ;
39	height: 35px }
40
41	.navigation .textlinks {
42	padding-left: 1em ;
43	text-align: left }
44
45	.navigation td, .navigation th {
46	padding-left: 0em ;
47	padding-right: 0em ;
48	vertical-align: middle }
49
50	.rfc2822 {
51	margin-top: 0.5em ;
52	margin-left: 0.5em ;
53	margin-right: 0.5em ;
54	margin-bottom: 0em }
55
56	.rfc2822 td {
57	text-align: left }
58
59	.rfc2822 th.field-name {
60	text-align: right ;
61	font-family: sans-serif ;
62	padding-right: 0.5em ;
63	font-weight: bold ;
64	margin-bottom: 0em }
65
66	a.toc-backref {
67	text-decoration: none ;
68	color: black }
69
70	body {
71	margin: 0px ;
72	margin-bottom: 1em ;
73	padding: 0px }
74
75	dd {
76	margin-bottom: 0.5em }
77
78	div.section {
79	margin-left: 1em ;
80	margin-right: 1em ;
81	margin-bottom: 1.5em }
82
83	div.section div.section {
84	margin-left: 0em ;
85	margin-right: 0em ;
86	margin-top: 1.5em }
87
88	div.abstract {
89	margin: 2em 5em }
90
91	div.abstract p.topic-title {
92	font-weight: bold ;
93	text-align: center }
94
95	div.attention, div.caution, div.danger, div.error, div.hint,
96	div.important, div.note, div.tip, div.warning {
97	margin: 2em ;
98	border: medium outset ;
99	padding: 1em }
100
101	div.attention p.admonition-title, div.caution p.admonition-title,
102	div.danger p.admonition-title, div.error p.admonition-title,
103	div.warning p.admonition-title {
104	color: red ;
105	font-weight: bold ;
106	font-family: sans-serif }
107
108	div.hint p.admonition-title, div.important p.admonition-title,
109	div.note p.admonition-title, div.tip p.admonition-title {
110	font-weight: bold ;
111	font-family: sans-serif }
112
113	div.figure {
114	margin-left: 2em }
115
116	div.footer, div.header {
117	font-size: smaller }
118
119	div.footer {
120	margin-left: 1em ;
121	margin-right: 1em }
122
123	div.system-messages {
124	margin: 5em }
125
126	div.system-messages h1 {
127	color: red }
128
129	div.system-message {
130	border: medium outset ;
131	padding: 1em }
132
133	div.system-message p.system-message-title {
134	color: red ;
135	font-weight: bold }
136
137	div.topic {
138	margin: 2em }
139
140	h1 {
141	font-family: sans-serif ;
142	font-size: large }
143
144	h2 {
145	font-family: sans-serif ;
146	font-size: medium }
147
148	h3 {
149	font-family: sans-serif ;
150	font-size: small }
151
152	h4 {
153	font-family: sans-serif ;
154	font-style: italic ;
155	font-size: small }
156
157	h5 {
158	font-family: sans-serif;
159	font-size: x-small }
160
161	h6 {
162	font-family: sans-serif;
163	font-style: italic ;
164	font-size: x-small }
165
166	.section hr {
167	width: 75% }
168
169	ol.simple, ul.simple {
170	margin-bottom: 1em }
171
172	ol.arabic {
173	list-style: decimal }
174
175	ol.loweralpha {
176	list-style: lower-alpha }
177
178	ol.upperalpha {
179	list-style: upper-alpha }
180
181	ol.lowerroman {
182	list-style: lower-roman }
183
184	ol.upperroman {
185	list-style: upper-roman }
186
187	p.caption {
188	font-style: italic }
189
190	p.credits {
191	font-style: italic ;
192	font-size: smaller }
193
194	p.label {
195	white-space: nowrap }
196
197	p.topic-title {
198	font-family: sans-serif ;
199	font-weight: bold }
200
201	pre.line-block {
202	font-family: serif ;
203	font-size: 100% }
204
205	pre.literal-block, pre.doctest-block {
206	margin-left: 2em ;
207	margin-right: 2em ;
208	background-color: #eeeeee }
209
210	span.classifier {
211	font-family: sans-serif ;
212	font-style: oblique }
213
214	span.classifier-delimiter {
215	font-family: sans-serif ;
216	font-weight: bold }
217
218	span.interpreted {
219	font-family: sans-serif }
220
221	span.option-argument {
222	font-style: italic }
223
224	span.pre {
225	white-space: pre }
226
227	span.problematic {
228	color: red }
229
230	table {
231	margin-top: 0.5em ;
232	margin-bottom: 0.5em }
233
234	td, th {
235	padding-left: 0.5em ;
236	padding-right: 0.5em ;
237	vertical-align: top }
238
239	td.num {
240	text-align: right }
241
242	th.field-name {
243	font-weight: bold ;
244	text-align: left ;
245	white-space: nowrap }
246
247	h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248	font-size: 100% }
249
250	tt {
251	background-color: #eeeeee }
252
253	ul.auto-toc {
254	list-style-type: none }
255
256	</style>
257	</head>
258	<body bgcolor="white">
259	<table class="navigation" cellpadding="0" cellspacing="0"
260	width="100%" border="0">
261	<tr><td class="navicon" width="150" height="35">
262	<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
263	<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
264	border="0" width="150" height="35" /></a></td>
265	<td class="textlinks" align="left">
266	[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
267	[<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
268	[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0046.txt">GLEP Source</a></b>]
269	</td></tr></table>
270	<table class="rfc2822 docutils field-list" frame="void" rules="none">
271	<col class="field-name" />
272	<col class="field-body" />
273	<tbody valign="top">
274	<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">46</td>
275	</tr>
276	<tr class="field"><th class="field-name">Title:</th><td class="field-body">Allow upstream tags in metadata.xml</td>
277	</tr>
278	<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
279	</tr>
280	<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">2006/03/06 03:17:07</a></td>
281	</tr>
282	<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org></td>
283	</tr>
284	<tr class="field"><th class="field-name">Status:</th><td class="field-body">Deferred</td>
285	</tr>
286	<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
287	</tr>
288	<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>
289	</tr>
290	<tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td>
291	</tr>
292	<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Dec-2005, 5-Mar-2006</td>
293	</tr>
294	</tbody>
295	</table>
296	<hr />
297	<div class="contents topic">
298	<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299	<ul class="simple">
300	<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
301	<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
302	<li><a class="reference" href="#specification" id="id4" name="id4">Specification</a></li>
303	<li><a class="reference" href="#backwards-compatibility" id="id5" name="id5">Backwards Compatibility</a></li>
304	<li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li>
305	</ul>
306	</div>
307	<div class="section">
308	<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
309	<p>Tree <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files are currently used to specify maintainer and
310	description information for packages. This GLEP proposes extensions to
311	<tt class="docutils literal"><span class="pre">metadata.xml</span></tt> to allow storage of information about upstream.</p>
312	</div>
313	<div class="section">
314	<h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
315	<p>The range of upstream-related data currently available to developers and
316	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
317	ebuilds.</p>
318	<p>There have been several attempts at creating tools that check a
319	package's versions against Freshmeat to see whether an ebuild version
320	bump is required. Currently identifying a package's Freshmeat entry is a
321	matter of guesswork, and not something that can reliably be automated.</p>
322	<p>Similarly, various scripts exist to check a package's status against a
323	specialist external data source. One of the authors, for example, has a
324	shell script hack that tries to determine whether any <tt class="docutils literal"><span class="pre">app-vim</span></tt>
325	packages need bumping by checking the associated <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
326	page. Again, tying packages to external data source entries is not
327	particulaly straight forward.</p>
328	<p>Making additional upstream-related data easily available will have other
329	benefits:</p>
330	<ul class="simple">
331	<li>It will allow systems such as the Packages website to provide more
332	useful information to end users.</li>
333	<li>It will reduce the time spent by developers trying to find how to
334	contact upstream.</li>
335	</ul>
336	</div>
337	<div class="section">
338	<h1><a class="toc-backref" href="#id4" id="specification" name="specification">Specification</a></h1>
339	<p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in
340	<tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Inside the upstream tag, developers should be able to
341	add upstream related information.</p>
342	<p>This GLEP defines the following four tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
343	<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
344	which are mandatory. Future GLEPs may extend this -- tools processing
345	metadata.xml should ignore unrecognized elements.</p>
346	<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
347	the person or organization responsible for upstream maintainership of
348	the package.</p>
349	<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name.</p>
350	<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@bar.bar">foo@bar.bar</a>.</p>
351	<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
352	<tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream changelog can be found.</p>
353	<p><tt class="docutils literal"><span class="pre">bugs-to</span></tt> should contain a place where bugs can be filed, a URL
354	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
355	with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
356	<p><tt class="docutils literal"><span class="pre">remote-id</span></tt> should specify a type of package identification tracker
357	and the identification that corresponds to the package in question.
358	<tt class="docutils literal"><span class="pre">remote-id</span></tt> should make it easier to index information such as its
359	Freshmeat ID or its CPAN name.</p>
360	<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
361	identifying the type of upstream source. Examples are <tt class="docutils literal"><span class="pre">freshmeat</span></tt>, in
362	which case the element content should be the Freshmeat ID or <tt class="docutils literal"><span class="pre">vim</span></tt>, in
363	which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
364	identifier. This GLEP does not specify a complete list of legal values
365	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
366	before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value.</p>
367	<p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
368	<pre class="literal-block">
369	<upstream>
370	<maintainer>
371	<name>Foo Bar</name>
372	<email>foo@bar.bar</email>
373	</maintainer>
374	<changelog>http://foo.bar/changelog.txt</changelog>
375	<bugs-to>https://bugs.foo.bar</bugs-to>
376	<remote-id type="freshmeat">12345</remote-id>
377	<remote-id type="sourceforge">foobar</remote-id>
378	</upstream>
379	</pre>
380	</div>
381	<div class="section">
382	<h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
383	<p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
384	in the new tags is not be mandatory. Any sane tool that currently
385	handles <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files will simply ignore unrecognised elements.</p>
386	</div>
387	<div class="section">
388	<h1><a class="toc-backref" href="#id6" id="copyright" name="copyright">Copyright</a></h1>
389	<p>This document has been placed in the public domain.</p>
390	<!-- vim: set ft=glep tw=72 : -->
391	</div>
392
393	</div>
394	<div class="footer">
395	<hr class="footer" />
396	<a class="reference" href="glep-0046.txt">View document source</a>.
397	Generated on: 2006-10-10 20:23 UTC.
398	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.
399
400	</div>
401	</body>
402	</html>
403