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 , Ciaran McCreesh Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 26-Dec-2005 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:: Foo Bar foo@bar.bar http://foo.bar/changelog.txt https://bugs.foo.bar 12345 foobar 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 :