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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download)
Thu Jan 24 13:00:09 2008 UTC (6 years, 2 months ago) by dev-zero
Branch: MAIN
Changes since 1.3: +42 -14 lines
File MIME type: text/plain
Updated glep-0046 according to the discussion on the gentoo.devel mailinglist

1 GLEP: 46
2 Title: Allow upstream tags in metadata.xml
3 Version: $Revision: 1.3 $
4 Last-Modified: $Date: 2007/04/21 03:13:16 $
5 Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org>
6 Status: Deferred
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 26-Dec-2005
10 Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008
11
12 Abstract
13 ========
14
15 Tree ``metadata.xml`` files are currently used to specify maintainer and
16 description information for packages. This GLEP proposes extensions to
17 ``metadata.xml`` to allow storage of information about upstream.
18
19 Motivation
20 ==========
21
22 The range of upstream-related data currently available to developers and
23 tool authors is currently limited to ``DESCRIPTION`` and ``HOMEPAGE`` in
24 ebuilds.
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.
49
50 Specification
51 =============
52
53 ``metadata.dtd`` should allow the use of a upstream tag in
54 ``metadata.xml``. Inside the upstream tag, developers should be able to
55 add upstream related information.
56
57 This GLEP defines the following five tags for ``upstream``:
58 ``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
59 which are mandatory. Future GLEPs may extend this -- tools processing
60 metadata.xml should ignore unrecognized elements.
61
62 ``maintainer`` can contain the tags ``name`` and ``email``, indicating
63 the person or organization responsible for upstream maintainership of
64 the package. The tag may appear more than once.
65
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``.
69
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.
74
75 ``name`` should contain a block of text with upstream's name, is mandatory
76 and can only appear once.
77
78 ``email`` should contain an e-mail address in the format ``foo@bar.bar``.
79
80 ``changelog`` should contain a URL prefixed with ``http://`` or
81 ``https://`` where the location of the upstream changelog can be found.
82
83 ``doc`` should contain a URL prefixed with with ``http://`` or
84 ``https://`` where the location of the upstream documentation can be found.
85 The link must not point to any third party documentation and must be version
86 independent. If the documentation is available in more than one language, a
87 ``lang`` attribute can be used which follows the same rules as the one
88 for ``longdescription``.
89
90 ``bugs-to`` should contain a place where bugs can be filed, a URL
91 prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
92 with ``mailto:``.
93
94 ``remote-id`` should specify a type of package identification tracker
95 and the identification that corresponds to the package in question.
96 ``remote-id`` should make it easier to index information such as its
97 Freshmeat ID or its CPAN name.
98
99 The ``remote-id`` element has a ``type`` attribute, which is a string
100 identifying the type of upstream source. Examples are ``freshmeat``, in
101 which case the element content should be the Freshmeat ID or ``vim``, in
102 which case the element content should be the ``vim.org`` script
103 identifier. This GLEP does not specify a complete list of legal values
104 for ``type`` -- developers should email the ``gentoo-dev`` mailing list
105 before using a new ``type`` value. The list of valid tags should be kept
106 in ``metadata/dtd/remote-id-tags.dtd``.
107
108 For example, a ``metadata.xml`` upstream snippet may look like::
109
110 <upstream>
111 <maintainer status="inactive">
112 <name>Foo Bar</name>
113 <email>foo@bar.bar</email>
114 </maintainer>
115 <maintainer status="active">
116 <name>Foo Gentoo</name>
117 <email>foo@gentoo.org</email>
118 </maintainer>
119 <changelog>http://foo.bar/changelog.txt</changelog>
120 <doc lang="en">http://foo.bar/doc/index.html</doc>
121 <doc lang="de">http://foo.bar./doc/index.de.html</doc>
122 <bugs-to>https://bugs.foo.bar</bugs-to>
123 <remote-id type="freshmeat">foobar</remote-id>
124 <remote-id type="sourceforge">foobar</remote-id>
125 </upstream>
126
127
128 Backwards Compatibility
129 =======================
130
131 No changes are necessary to existing ``metadata.xml`` files. Information
132 in the new tags is not mandatory. Tools that currently read
133 ``metadata.xml`` files may break if written poorly; well written tools
134 should just ignore the additional elements.
135
136 Copyright
137 =========
138
139 This document has been placed in the public domain.
140
141 .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20