en/glep/glep-0046.txt

GLEP: 46
Title: Allow upstream tags in metadata.xml
Version: $Revision: 1.4 $
Last-Modified: $Date: 2008/01/24 13:00:09 $
Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org>
Status: Deferred
Type: Standards Track
Content-Type: text/x-rst
Created: 26-Dec-2005
Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008

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.

* It will give treecleaners additional information to decide whether
  a package can be removed from the tree.

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 five tags for ``upstream``:
``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` 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. The tag may appear more than once.

The ``maintainer`` element has a ``status`` attribute, which is one of
``active`` or ``inactive``. This attribute is not mandatory. The absence of it
shall be interpreted as ``unknown``.

The ``maintainer`` element can be the same as the top-level ``maintainer``
element in cases where a developer decides to maintain the package in
addition to/instead of the original upstream. In such cases a ``maintainer``
entry for the original upstream should be present.

``name`` should contain a block of text with upstream's name, is mandatory
and can only appear once.

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

``changelog`` should contain a URL where the location of the upstream
changelog can be found. The URL must be version independent and must point to
a changelog which is only updated on new releases of the corresponding
package. (This also implies that one can link to an automatically updated
changelog in case of vcs snapshots only.)

``doc`` should contain a URL where the location of the upstream
documentation can be found. The link must not point to any third party
documentation and must be version independent. If the documentation is
available in more than one language, a ``lang`` attribute can be used
which follows the same rules as the one for ``longdescription``.

``bugs-to`` should contain a place where bugs can be filed, a URL 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. The list of valid tags should be kept
in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``.

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

        <upstream>
                <maintainer status="inactive">
                        <name>Foo Bar</name>
                        <email>foo@bar.bar</email>
                </maintainer>
                <maintainer status="active">
                        <name>Foo Gentoo</name>
                        <email>foo@gentoo.org</email>
                </maintainer>
                <changelog>http://foo.bar/changelog.txt</changelog>
                <doc lang="en">http://foo.bar/doc/index.html</doc>
                <doc lang="de">http://foo.bar/doc/index.de.html</doc>
                <bugs-to>https://bugs.foo.bar</bugs-to>
                <remote-id type="freshmeat">foobar</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 mandatory. Tools that currently read
``metadata.xml`` files may break if written poorly; well written tools
should just ignore the additional elements.

Notes
=====

The specified URLs must include a protocol as described in RFC 3986.
Furthermore the most common protocol should be used in case of several
possibilities (http should be favoured over https or ftp over gopher or svn,
etc).


Copyright
=========

This document has been placed in the public domain.

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

1	ciaranm	1.1	GLEP: 46
2			Title: Allow upstream tags in metadata.xml
3	dev-zero	1.5	Version: $Revision: 1.4 $
4			Last-Modified: $Date: 2008/01/24 13:00:09 $
5	dev-zero	1.4	Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org>
6	antarus	1.3	Status: Deferred
7	ciaranm	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 26-Dec-2005
10	dev-zero	1.4	Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008
11	ciaranm	1.1
12			Abstract
13			========
14
15	ciaranm	1.2	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	ciaranm	1.1
19			Motivation
20			==========
21
22	ciaranm	1.2	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	ciaranm	1.1
41	ciaranm	1.2	* 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	ciaranm	1.1
47	dev-zero	1.4	* It will give treecleaners additional information to decide whether
48			a package can be removed from the tree.
49
50	ciaranm	1.1	Specification
51			=============
52
53	ciaranm	1.2	``metadata.dtd`` should allow the use of a upstream tag in
54			``metadata.xml``. Inside the upstream tag, developers should be able to
55			add upstream related information.
56	ciaranm	1.1
57	dev-zero	1.4	This GLEP defines the following five tags for ``upstream``:
58			``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
59	ciaranm	1.2	which are mandatory. Future GLEPs may extend this -- tools processing
60			metadata.xml should ignore unrecognized elements.
61
62			``maintainer`` can contain the tags ``name`` and ``email``, indicating
63			the person or organization responsible for upstream maintainership of
64	dev-zero	1.4	the package. The tag may appear more than once.
65
66			The ``maintainer`` element has a ``status`` attribute, which is one of
67			``active`` or ``inactive``. This attribute is not mandatory. The absence of it
68			shall be interpreted as ``unknown``.
69
70			The ``maintainer`` element can be the same as the top-level ``maintainer``
71			element in cases where a developer decides to maintain the package in
72			addition to/instead of the original upstream. In such cases a ``maintainer``
73			entry for the original upstream should be present.
74	ciaranm	1.1
75	dev-zero	1.4	``name`` should contain a block of text with upstream's name, is mandatory
76			and can only appear once.
77	ciaranm	1.1
78	dev-zero	1.4	``email`` should contain an e-mail address in the format ``foo@bar.bar``.
79	ciaranm	1.1
80	dev-zero	1.5	``changelog`` should contain a URL where the location of the upstream
81			changelog can be found. The URL must be version independent and must point to
82			a changelog which is only updated on new releases of the corresponding
83			package. (This also implies that one can link to an automatically updated
84			changelog in case of vcs snapshots only.)
85
86			``doc`` should contain a URL where the location of the upstream
87			documentation can be found. The link must not point to any third party
88			documentation and must be version independent. If the documentation is
89			available in more than one language, a ``lang`` attribute can be used
90			which follows the same rules as the one for ``longdescription``.
91	ciaranm	1.1
92	dev-zero	1.5	``bugs-to`` should contain a place where bugs can be filed, a URL or an
93			e-mail address prefixed with ``mailto:``.
94	ciaranm	1.2
95			``remote-id`` should specify a type of package identification tracker
96			and the identification that corresponds to the package in question.
97			``remote-id`` should make it easier to index information such as its
98			Freshmeat ID or its CPAN name.
99
100			The ``remote-id`` element has a ``type`` attribute, which is a string
101			identifying the type of upstream source. Examples are ``freshmeat``, in
102			which case the element content should be the Freshmeat ID or ``vim``, in
103			which case the element content should be the ``vim.org`` script
104			identifier. This GLEP does not specify a complete list of legal values
105			for ``type`` -- developers should email the ``gentoo-dev`` mailing list
106	dev-zero	1.4	before using a new ``type`` value. The list of valid tags should be kept
107	dev-zero	1.5	in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``.
108	ciaranm	1.1
109	ciaranm	1.2	For example, a ``metadata.xml`` upstream snippet may look like::
110	ciaranm	1.1
111			<upstream>
112	dev-zero	1.4	<maintainer status="inactive">
113	ciaranm	1.2	<name>Foo Bar</name>
114			<email>foo@bar.bar</email>
115			</maintainer>
116	dev-zero	1.4	<maintainer status="active">
117			<name>Foo Gentoo</name>
118			<email>foo@gentoo.org</email>
119			</maintainer>
120	ciaranm	1.2	<changelog>http://foo.bar/changelog.txt</changelog>
121	dev-zero	1.4	<doc lang="en">http://foo.bar/doc/index.html</doc>
122	dev-zero	1.5	<doc lang="de">http://foo.bar/doc/index.de.html</doc>
123	ciaranm	1.2	<bugs-to>https://bugs.foo.bar</bugs-to>
124	dev-zero	1.4	<remote-id type="freshmeat">foobar</remote-id>
125	ciaranm	1.2	<remote-id type="sourceforge">foobar</remote-id>
126	ciaranm	1.1	</upstream>
127
128
129			Backwards Compatibility
130			=======================
131
132	ciaranm	1.2	No changes are necessary to existing ``metadata.xml`` files. Information
133	dev-zero	1.4	in the new tags is not mandatory. Tools that currently read
134			``metadata.xml`` files may break if written poorly; well written tools
135			should just ignore the additional elements.
136	ciaranm	1.1
137	dev-zero	1.5	Notes
138			=====
139
140			The specified URLs must include a protocol as described in RFC 3986.
141			Furthermore the most common protocol should be used in case of several
142			possibilities (http should be favoured over https or ftp over gopher or svn,
143			etc).
144
145
146	ciaranm	1.1	Copyright
147			=========
148
149			This document has been placed in the public domain.
150
151	ciaranm	1.2	.. vim: set ft=glep tw=72 :
152