Rename all GLEPs to .rst

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 :