GLEP:46
Title:Allow upstream tags in metadata.xml
Version:1.4
Last-Modified:2008/01/24 13:00:09
Author:Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org>, Tiziano Müller <dev-zero at 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

Contents

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:

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 prefixed with http:// or https:// where the location of the upstream changelog can be found.

doc should contain a URL prefixed with with http:// or https:// 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 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. The list of valid tags should be kept in metadata/dtd/remote-id-tags.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.

Copyright

This document has been placed in the public domain.