Title:Allow upstream tags in metadata.xml
Last-Modified:2007/04/21 03:13:16
Author:Marcelo Goes <vanquirius at>, Ciaran McCreesh <ciaranm at>
Type:Standards Track
Post-History:26-Dec-2005, 5-Mar-2006



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.


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 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:


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

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 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:

                <name>Foo Bar</name>
        <remote-id type="freshmeat">12345</remote-id>
        <remote-id type="sourceforge">foobar</remote-id>

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.


This document has been placed in the public domain.