/[gentoo]/xml/htdocs/proj/en/glep/glep-0046.txt

Diff of /xml/htdocs/proj/en/glep/glep-0046.txt

Parent Directory | Revision Log | View Patch Patch

Revision 1.1		Revision 1.6
1	GLEP: 46	1	GLEP: 46
2	Title: Allow upstream tags in metadata.xml	2	Title: Allow upstream tags in metadata.xml
3	Version: $Revision: 1.1 $	3	Version: $Revision: 1.6 $
4	Last-Modified: $Date: 2005/12/27 00:26:58 $	4	Last-Modified: $Date: 2008/05/10 07:50:43 $
5	Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>	5	Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org>
6	Status: Draft	6	Status: Accepted
7	Type: Standards Track	7	Type: Standards Track
8	Content-Type: text/x-rst	8	Content-Type: text/x-rst
9	Created: 26-Dec-2005	9	Created: 26-Dec-2005
		10	Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008, 10-May-2008
10		11
11	Abstract	12	Abstract
12	========	13	========
13		14
14	``metadata.xml`` should allow the use of tags to add information related to	15	Tree ``metadata.xml`` files are currently used to specify maintainer and
15	upstream, such as who the upstream maintainers are, the upstream changelog and	16	description information for packages. This GLEP proposes extensions to
16	where to report bugs.	17	``metadata.xml`` to allow storage of information about upstream.
17
18		18
19	Motivation	19	Motivation
20	==========	20	==========
21		21
22	Allowing developers to add upstream information in ``metadata.xml`` will make it	22	The range of upstream-related data currently available to developers and
23	easier, faster and more reliable to share it with other developers. Having	23	tool authors is currently limited to ``DESCRIPTION`` and ``HOMEPAGE`` in
24	information from upstream should avoid duplicated work in tasks such as browsing	24	ebuilds.
25	upstream's Homepage and mailing lists.
26		25
		26	There have been several attempts at creating tools that check a
		27	package's versions against Freshmeat to see whether an ebuild version
		28	bump is required. Currently identifying a package's Freshmeat entry is a
		29	matter of guesswork, and not something that can reliably be automated.
		30
		31	Similarly, various scripts exist to check a package's status against a
		32	specialist external data source. One of the authors, for example, has a
		33	shell script hack that tries to determine whether any ``app-vim``
		34	packages need bumping by checking the associated ``vim.org`` script
		35	page. Again, tying packages to external data source entries is not
		36	particulaly straight forward.
		37
		38	Making additional upstream-related data easily available will have other
		39	benefits:
		40
		41	* It will allow systems such as the Packages website to provide more
		42	useful information to end users.
		43
		44	* It will reduce the time spent by developers trying to find how to
		45	contact upstream.
		46
		47	* It will give treecleaners additional information to decide whether
		48	a package can be removed from the tree.
27		49
28	Specification	50	Specification
29	=============	51	=============
30		52
31	``metadata.dtd`` should allow the use of a upstream tag in ``metadata.xml``.	53	``metadata.dtd`` should allow the use of a upstream tag in
32	Inside the upstream tag, developers should be able to add upstream information	54	``metadata.xml``. Inside the upstream tag, developers should be able to
33	in the tags named ``maintainer, ``changelog``, ``bugs-to`` and ``remote-id``.	55	add upstream related information.
34		56
35	This GLEP defines the following four tags for ``upstream``:	57	This GLEP defines the following five tags for ``upstream``:
36	``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of which are	58	``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
37	mandatory. Future GLEPs may extend this -- tools processing metadata.xml should	59	which are mandatory. Future GLEPs may extend this -- tools processing
38	ignore unrecognized elements.	60	metadata.xml should ignore unrecognized elements.
39		61
40	``maintainer`` can contain the tags ``name`` and ``email``, indicating the	62	``maintainer`` can contain the tags ``name`` and ``email``, indicating
41	person/organization responsible for upstream maintainership of the package.	63	the person or organization responsible for upstream maintainership of
		64	the package. The tag may appear more than once.
42		65
43	``name`` should contain a block of text with upstream's name.	66	The ``maintainer`` element has a ``status`` attribute, which is one of
		67	``active`` or ``inactive``. This attribute is not mandatory. The absence of it
		68	shall be interpreted as ``unknown``.
44		69
45	``email`` should contain an e-mail address in the format foo@bar.bar.	70	The ``maintainer`` element can be the same as the top-level ``maintainer``
		71	element in cases where a developer decides to maintain the package in
		72	addition to/instead of the original upstream. In such cases a ``maintainer``
		73	entry for the original upstream should be present.
46		74
47	``changelog`` should contain a URL prefixed with http or https where the	75	``name`` should contain a block of text with upstream's name, is mandatory
48	location of the upstream changelog can be found.	76	and can only appear once.
49		77
50	``bugs-to`` should contain a place where bugs can be filed, a URL prefixed with	78	``email`` should contain an e-mail address in the format ``foo@bar.bar``.
51	http or https or an e-mail address.
52		79
53	``remote-id`` should specify a type of package identification tracker and the	80	``changelog`` should contain a URL where the location of the upstream
54	identification that corresponds to the package in question. ``remote-id`` should	81	changelog can be found. The URL must be version independent and must point to
55	make it easier to index information like its identification in freshmeat or its	82	a changelog which is only updated on new releases of the corresponding
56	cpan identification.	83	package. (This also implies that one can link to an automatically updated
		84	changelog in case of vcs snapshots only.)
57		85
58	For example::	86	``doc`` should contain a URL where the location of the upstream
		87	documentation can be found. The link must not point to any third party
		88	documentation and must be version independent. If the documentation is
		89	available in more than one language, a ``lang`` attribute can be used
		90	which follows the same rules as the one for ``longdescription``.
		91
		92	``bugs-to`` should contain a place where bugs can be filed, a URL or an
		93	e-mail address prefixed with ``mailto:``.
		94
		95	``remote-id`` should specify a type of package identification tracker
		96	and the identification that corresponds to the package in question.
		97	``remote-id`` should make it easier to index information such as its
		98	Freshmeat ID or its CPAN name.
		99
		100	The ``remote-id`` element has a ``type`` attribute, which is a string
		101	identifying the type of upstream source. Examples are ``freshmeat``, in
		102	which case the element content should be the Freshmeat ID or ``vim``, in
		103	which case the element content should be the ``vim.org`` script
		104	identifier. This GLEP does not specify a complete list of legal values
		105	for ``type`` -- developers should email the ``gentoo-dev`` mailing list
		106	before using a new ``type`` value. The list of valid tags should be kept
		107	in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``.
		108
		109	For example, a ``metadata.xml`` upstream snippet may look like::
59		110
60	<upstream>	111	<upstream>
61	<maintainer>	112	<maintainer status="inactive">
62	<name>Foo Bar</name>	113	<name>Foo Bar</name>
63	<email>foo@bar.bar</email>	114	<email>foo@bar.bar</email>
64	</maintainer>	115	</maintainer>
		116	<maintainer status="active">
		117	<name>Foo Gentoo</name>
		118	<email>foo@gentoo.org</email>
		119	</maintainer>
65	<changelog>http://foo.bar/changelog.txt</changelog>	120	<changelog>http://foo.bar/changelog.txt</changelog>
		121	<doc lang="en">http://foo.bar/doc/index.html</doc>
		122	<doc lang="de">http://foo.bar/doc/index.de.html</doc>
66	<bugs-to>https://bugs.foo.bar</bugs-to>	123	<bugs-to>https://bugs.foo.bar</bugs-to>
67	<remote-id type="freshmeat">12345</remote-id>	124	<remote-id type="freshmeat">foobar</remote-id>
68	<remote-id type="sourceforge">foobar</remote-id>	125	<remote-id type="sourceforge">foobar</remote-id>
69	</upstream>	126	</upstream>
70		127
71		128
72	Backwards Compatibility	129	Backwards Compatibility
73	=======================	130	=======================
74		131
75	No changes are necessary to existing ``metadata.xml``. Information in the new	132	No changes are necessary to existing ``metadata.xml`` files. Information
76	tags should not be mandatory.	133	in the new tags is not mandatory. Tools that currently read
		134	``metadata.xml`` files may break if written poorly; well written tools
		135	should just ignore the additional elements.
		136
		137	Notes
		138	=====
		139
		140	The specified URLs must include a protocol as described in RFC 3986.
		141	Furthermore the most common protocol should be used in case of several
		142	possibilities (http should be favoured over https or ftp over gopher or svn,
		143	etc).
77		144
78		145
79	Copyright	146	Copyright
80	=========	147	=========
81		148
82	This document has been placed in the public domain.	149	This document has been placed in the public domain.
83		150
		151	.. vim: set ft=glep tw=72 :
		152

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.6
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.6
-Removed from v.1.1
+Added in v.1.6

	ViewVC Help
Powered by ViewVC 1.1.13