While some people already discovered the upstream metadata tags, there
are only 8 ebuilds using them so far. Mostly I am to blame for that,
since I forgot to send out a proper announcement. While all the required
information can be found in the Developer Handbook [1], here is a short
summary:

The upstream tags are meant as a way to track information about
upstream, like:
- the upstream status (can make treecleaners lives easier)
- online documentation links (a shortcut for the user)
- not-so-obvious contact/bug-reporting information
- id of a hosting or indexing site (automated version bump checks)
- their alignment (mostly chaotic-neutral ;-)

An example (copied from GLEP 46 [2] itself):
<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>

Please note:
- the <maintainer> tag in <upstream> is only for specifying an upstream
maintainer name and e-mail address and does not specify the ebuild
maintainer (although it may be the same if you decide to become
upstream).
- the type attribute for <remote-id> is currently one of (freshmeat|
sourceforge|cpan|vim), send a mail to gentoo-dev before adding
additional sites
- the data in the <remote-id> tags is an id which uniquely identifies
the project on that site:
    - for type="vim": the script_id (example: 2586)
    - for type="freshmeat": the project name (example: aria2)
    - for type="sourceforge": the project name (example: liferea)
    - for type="cpan": the module name (example: Pod-Index)

Regards,
Tiziano



[1]:
http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
[2]: http://www.gentoo.org/proj/en/glep/glep-0046.html


-- 
Tiziano Müller
Gentoo Linux Developer
Areas of responsibility:
  Samba, PostgreSQL, CPP, Python, sysadmin, GLEP Editor
E-Mail   : dev-zero@gentoo.org
GnuPG FP : F327 283A E769 2E36 18D5  4DE2 1B05 6A63 AE9C 1E30