en/glep/glep-0046.txt

GLEP: 46
Title: Allow upstream tags in metadata.xml
Version: $Revision: 1.1 $
Last-Modified: $Date: 2005/12/27 00:26:58 $
Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 26-Dec-2005
Post-History: 26-Dec-2005, 5-Mar-2006

Abstract
========

Tree ``metadata.xml`` files are currently used to specify maintainer and
description information for packages. This GLEP proposes extensions to
``metadata.xml`` to allow storage of information about upstream.

Motivation
==========

The range of upstream-related data currently available to developers and
tool authors is currently limited to ``DESCRIPTION`` and ``HOMEPAGE`` in
ebuilds.

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.

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 ``app-vim``
packages need bumping by checking the associated ``vim.org`` script
page. Again, tying packages to external data source entries is not
particulaly straight forward.

Making additional upstream-related data easily available will have other
benefits:

* It will allow systems such as the Packages website to provide more
  useful information to end users.

* It will reduce the time spent by developers trying to find how to
  contact upstream.

Specification
=============

``metadata.dtd`` should allow the use of a upstream tag in
``metadata.xml``.  Inside the upstream tag, developers should be able to
add upstream related information.

This GLEP defines the following four tags for ``upstream``:
``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of
which are mandatory. Future GLEPs may extend this -- tools processing
metadata.xml should ignore unrecognized elements.

``maintainer`` can contain the tags ``name`` and ``email``, indicating
the person or organization responsible for upstream maintainership of
the package.

``name`` should contain a block of text with upstream's name.

``email`` should contain an e-mail address in the format foo@bar.bar.

``changelog`` should contain a URL prefixed with ``http://`` or
``https://`` where the location of the upstream changelog can be found.

``bugs-to`` should contain a place where bugs can be filed, a URL
prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
with ``mailto:``.

``remote-id`` should specify a type of package identification tracker
and the identification that corresponds to the package in question.
``remote-id`` should make it easier to index information such as its
Freshmeat ID or its CPAN name.

The ``remote-id`` element has a ``type`` attribute, which is a string
identifying the type of upstream source. Examples are ``freshmeat``, in
which case the element content should be the Freshmeat ID or ``vim``, in
which case the element content should be the ``vim.org`` script
identifier. This GLEP does not specify a complete list of legal values
for ``type`` -- developers should email the ``gentoo-dev`` mailing list
before using a new ``type`` value.

For example, a ``metadata.xml`` upstream snippet may look like::

        <upstream>
                <maintainer>
                        <name>Foo Bar</name>
                        <email>foo@bar.bar</email>
                </maintainer>
                <changelog>http://foo.bar/changelog.txt</changelog>
                <bugs-to>https://bugs.foo.bar</bugs-to>
                <remote-id type="freshmeat">12345</remote-id>
                <remote-id type="sourceforge">foobar</remote-id>
        </upstream>


Backwards Compatibility
=======================

No changes are necessary to existing ``metadata.xml`` files. Information
in the new tags is not be mandatory. Any sane tool that currently
handles ``metadata.xml`` files will simply ignore unrecognised elements.

Copyright
=========

This document has been placed in the public domain.

.. vim: set ft=glep tw=72 :

1	GLEP: 46
2	Title: Allow upstream tags in metadata.xml
3	Version: $Revision: 1.1 $
4	Last-Modified: $Date: 2005/12/27 00:26:58 $
5	Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>
6	Status: Draft
7	Type: Standards Track
8	Content-Type: text/x-rst
9	Created: 26-Dec-2005
10	Post-History: 26-Dec-2005, 5-Mar-2006
11
12	Abstract
13	========
14
15	Tree ``metadata.xml`` files are currently used to specify maintainer and
16	description information for packages. This GLEP proposes extensions to
17	``metadata.xml`` to allow storage of information about upstream.
18
19	Motivation
20	==========
21
22	The range of upstream-related data currently available to developers and
23	tool authors is currently limited to ``DESCRIPTION`` and ``HOMEPAGE`` in
24	ebuilds.
25
26	There have been several attempts at creating tools that check a
27	package's versions against Freshmeat to see whether an ebuild version
28	bump is required. Currently identifying a package's Freshmeat entry is a
29	matter of guesswork, and not something that can reliably be automated.
30
31	Similarly, various scripts exist to check a package's status against a
32	specialist external data source. One of the authors, for example, has a
33	shell script hack that tries to determine whether any ``app-vim``
34	packages need bumping by checking the associated ``vim.org`` script
35	page. Again, tying packages to external data source entries is not
36	particulaly straight forward.
37
38	Making additional upstream-related data easily available will have other
39	benefits:
40
41	* It will allow systems such as the Packages website to provide more
42	useful information to end users.
43
44	* It will reduce the time spent by developers trying to find how to
45	contact upstream.
46
47	Specification
48	=============
49
50	``metadata.dtd`` should allow the use of a upstream tag in
51	``metadata.xml``. Inside the upstream tag, developers should be able to
52	add upstream related information.
53
54	This GLEP defines the following four tags for ``upstream``:
55	``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of
56	which are mandatory. Future GLEPs may extend this -- tools processing
57	metadata.xml should ignore unrecognized elements.
58
59	``maintainer`` can contain the tags ``name`` and ``email``, indicating
60	the person or organization responsible for upstream maintainership of
61	the package.
62
63	``name`` should contain a block of text with upstream's name.
64
65	``email`` should contain an e-mail address in the format foo@bar.bar.
66
67	``changelog`` should contain a URL prefixed with ``http://`` or
68	``https://`` where the location of the upstream changelog can be found.
69
70	``bugs-to`` should contain a place where bugs can be filed, a URL
71	prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
72	with ``mailto:``.
73
74	``remote-id`` should specify a type of package identification tracker
75	and the identification that corresponds to the package in question.
76	``remote-id`` should make it easier to index information such as its
77	Freshmeat ID or its CPAN name.
78
79	The ``remote-id`` element has a ``type`` attribute, which is a string
80	identifying the type of upstream source. Examples are ``freshmeat``, in
81	which case the element content should be the Freshmeat ID or ``vim``, in
82	which case the element content should be the ``vim.org`` script
83	identifier. This GLEP does not specify a complete list of legal values
84	for ``type`` -- developers should email the ``gentoo-dev`` mailing list
85	before using a new ``type`` value.
86
87	For example, a ``metadata.xml`` upstream snippet may look like::
88
89	<upstream>
90	<maintainer>
91	<name>Foo Bar</name>
92	<email>foo@bar.bar</email>
93	</maintainer>
94	<changelog>http://foo.bar/changelog.txt</changelog>
95	<bugs-to>https://bugs.foo.bar</bugs-to>
96	<remote-id type="freshmeat">12345</remote-id>
97	<remote-id type="sourceforge">foobar</remote-id>
98	</upstream>
99
100
101	Backwards Compatibility
102	=======================
103
104	No changes are necessary to existing ``metadata.xml`` files. Information
105	in the new tags is not be mandatory. Any sane tool that currently
106	handles ``metadata.xml`` files will simply ignore unrecognised elements.
107
108	Copyright
109	=========
110
111	This document has been placed in the public domain.
112
113	.. vim: set ft=glep tw=72 :
114