Hello, I am basically mailing this new draft on behalf of Ciaran, I just ok'd it :-). Please read and comment.
Cheers, Marcelo -- Marcelo Góes [EMAIL PROTECTED] [EMAIL PROTECTED]
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 <[EMAIL PROTECTED]>, Ciaran McCreesh <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] ``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>[EMAIL PROTECTED]</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 :
