--- xml/htdocs/proj/en/glep/glep-0046.html 2005/12/27 00:26:58 1.1 +++ xml/htdocs/proj/en/glep/glep-0046.html 2006/03/06 03:17:07 1.2 @@ -8,9 +8,252 @@ --> - + GLEP 46 -- Allow upstream tags in metadata.xml - + @@ -32,9 +275,9 @@ - + - + @@ -42,15 +285,17 @@ - + + +
Title:Allow upstream tags in metadata.xml
Version:1.0
Version:1.1
Last-Modified:2005/12/26 20:00:00
Last-Modified:2005/12/27 00:26:58
Author:Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org>
Type:Standards Track
Content-Type:text/x-rst
Content-Type:text/x-rst
Created:26-Dec-2005
Post-History:26-Dec-2005, 5-Mar-2006

-
-

Contents

+
+

Contents

-
-

Abstract

-

metadata.xml should allow the use of tags to add information related to -upstream, such as who the upstream maintainers are, the upstream changelog and -where to report bugs.

-
-
-

Motivation

-

Allowing developers to add upstream information in metadata.xml will make it -easier, faster and more reliable to share it with other developers. Having -information from upstream should avoid duplicated work in tasks such as browsing -upstream's Homepage and mailing lists.

-
-
-

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 information -in the tags named maintainer, ``changelog, bugs-to and remote-id.

+
+

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/organization responsible for upstream maintainership of the package.

+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.

-

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 like its identification in freshmeat or its -cpan identification.

-

For example:

+

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>
+        <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. Information in the new -tags should not be mandatory.

+
+

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.

-