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