--- 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 @@ -->- +
|Title:||Allow upstream tags in metadata.xml|
|Author:||Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org>|
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.-
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.-
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.+
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.+
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:+
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 firstname.lastname@example.org.-
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.-
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@example.com</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>firstname.lastname@example.org</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>
No changes are necessary to existing metadata.xml. Information in the new -tags should not be mandatory.+
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.