--- xml/htdocs/proj/en/glep/glep-0046.html 2007/10/14 17:00:15 1.6 +++ xml/htdocs/proj/en/glep/glep-0046.html 2008/01/24 13:00:09 1.7 @@ -32,7 +32,7 @@ Last-Modified:2007/04/21 03:13:16 -Author:Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org> +Author:Marcelo Goes <vanquirius at gentoo.org>, Ciaran McCreesh <ciaranm at gentoo.org>, Tiziano Müller <dev-zero at gentoo.org> Status:Deferred @@ -42,7 +42,7 @@ Created:26-Dec-2005 -Post-History:26-Dec-2005, 5-Mar-2006 +Post-History:26-Dec-2005, 5-Mar-2006, 24-Jan-2008 @@ -85,6 +85,8 @@ 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.
  • @@ -92,17 +94,31 @@

    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 +

    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.

    -

    name should contain a block of text with upstream's name.

    -

    email should contain an e-mail address in the format foo@bar.bar.

    +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 prefixed with http:// or https:// where the location of the upstream changelog can be found.

    +

    doc should contain a URL prefixed with with http:// or +https:// 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 prefixed with http:// or https:// or an e-mail address prefixed with mailto:.

    @@ -116,17 +132,24 @@ 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.

    +before using a new type value. The list of valid tags should be kept +in metadata/dtd/remote-id-tags.dtd.

    For example, a metadata.xml upstream snippet may look like:

     <upstream>
    -        <maintainer>
    +        <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">12345</remote-id>
    +        <remote-id type="freshmeat">foobar</remote-id>
             <remote-id type="sourceforge">foobar</remote-id>
     </upstream>
     
    @@ -134,8 +157,9 @@

    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.

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

    Copyright

    @@ -147,7 +171,7 @@