[gentoo-dev] New Glep 46 Draft: Allow upstream tags in metadata.xml

["Marcelo Góes" <vanquirius@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 200 bytes --]

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
marcelogoes@gmail.com
vanquirius@gentoo.org

[-- Attachment #2: glep-0046.txt --]
[-- Type: text/plain, Size: 4093 bytes --]

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 <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>
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::

	<upstream>
		<maintainer>
			<name>Foo Bar</name>
			<email>foo@bar.bar</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 :