diff options
author | 2017-09-14 23:14:39 +0200 | |
---|---|---|
committer | 2017-10-09 12:08:51 +0200 | |
commit | c6fe2071a2e83be2203196ad7f9459941821a034 (patch) | |
tree | d81e1d9898c05917e05203af9803b581dff0d915 /glep-0046.rst | |
parent | glep-0045: Mark Final since GLEP 1 now uses ISO 8601 dates (diff) | |
download | glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.gz glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.bz2 glep-c6fe2071a2e83be2203196ad7f9459941821a034.zip |
Rename all GLEPs to .rst
Diffstat (limited to 'glep-0046.rst')
-rw-r--r-- | glep-0046.rst | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/glep-0046.rst b/glep-0046.rst new file mode 100644 index 0000000..4ec9e37 --- /dev/null +++ b/glep-0046.rst @@ -0,0 +1,154 @@ +GLEP: 46 +Title: Allow upstream tags in metadata.xml +Version: $Revision$ +Last-Modified: $Date$ +Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org> +Status: Accepted +Type: Standards Track +Content-Type: text/x-rst +Created: 26-Dec-2005 +Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008, 10-May-2008 +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:: + + <upstream> + <maintainer status="inactive"> + <name>Foo Bar</name> + <email>foo@bar.bar</email> + </maintainer> + <maintainer status="active"> + <name>Foo Gentoo</name> + <email>foo@gentoo.org</email> + </maintainer> + <changelog>http://foo.bar/changelog.txt</changelog> + <doc lang="en">http://foo.bar/doc/index.html</doc> + <doc lang="de">http://foo.bar/doc/index.de.html</doc> + <bugs-to>https://bugs.foo.bar</bugs-to> + <remote-id type="freshmeat">foobar</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 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 +http://creativecommons.org/licenses/by-sa/3.0/. + +.. vim: set ft=glep tw=72 : |