--- GLEP: 46 Title: Allow upstream tags in metadata.xml Author: Marcelo Goes , Ciaran McCreesh , Tiziano Müller Type: Standards Track Status: Replaced Version: 1 Created: 2005-12-26 Last-Modified: 2023-09-15 Post-History: 2005-12-26, 2006-03-05, 2008-01-21, 2008-03-25 Content-Type: text/x-rst Replaced-By: 68 --- 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 particularly 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:: Foo Bar foo@bar.bar Foo Gentoo foo@gentoo.org http://foo.bar/changelog.txt http://foo.bar/doc/index.html http://foo.bar/doc/index.de.html https://bugs.foo.bar foobar foobar 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 work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/3.0/. .. vim: set ft=glep tw=72 :