/[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.5 - (hide annotations) (download)
Thu Apr 3 13:35:26 2008 UTC (6 years, 8 months ago) by dev-zero
Branch: MAIN
Changes since 1.4: +26 -16 lines
File MIME type: text/plain
Changed as announced in message to the gentoo.dev mailinglist at 03/25/2008

1 ciaranm 1.1 GLEP: 46
2     Title: Allow upstream tags in metadata.xml
3 dev-zero 1.5 Version: $Revision: 1.4 $
4     Last-Modified: $Date: 2008/01/24 13:00:09 $
5 dev-zero 1.4 Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org>
6 antarus 1.3 Status: Deferred
7 ciaranm 1.1 Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 26-Dec-2005
10 dev-zero 1.4 Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008
11 ciaranm 1.1
12     Abstract
13     ========
14    
15 ciaranm 1.2 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 ciaranm 1.1
19     Motivation
20     ==========
21    
22 ciaranm 1.2 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 ciaranm 1.1
41 ciaranm 1.2 * 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 ciaranm 1.1
47 dev-zero 1.4 * It will give treecleaners additional information to decide whether
48     a package can be removed from the tree.
49    
50 ciaranm 1.1 Specification
51     =============
52    
53 ciaranm 1.2 ``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 ciaranm 1.1
57 dev-zero 1.4 This GLEP defines the following five tags for ``upstream``:
58     ``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
59 ciaranm 1.2 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 dev-zero 1.4 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 ciaranm 1.1
75 dev-zero 1.4 ``name`` should contain a block of text with upstream's name, is mandatory
76     and can only appear once.
77 ciaranm 1.1
78 dev-zero 1.4 ``email`` should contain an e-mail address in the format ``foo@bar.bar``.
79 ciaranm 1.1
80 dev-zero 1.5 ``changelog`` should contain a URL where the location of the upstream
81     changelog can be found. The URL must be version independent and must point to
82     a changelog which is only updated on new releases of the corresponding
83     package. (This also implies that one can link to an automatically updated
84     changelog in case of vcs snapshots only.)
85    
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 ciaranm 1.1
92 dev-zero 1.5 ``bugs-to`` should contain a place where bugs can be filed, a URL or an
93     e-mail address prefixed with ``mailto:``.
94 ciaranm 1.2
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 dev-zero 1.4 before using a new ``type`` value. The list of valid tags should be kept
107 dev-zero 1.5 in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``.
108 ciaranm 1.1
109 ciaranm 1.2 For example, a ``metadata.xml`` upstream snippet may look like::
110 ciaranm 1.1
111     <upstream>
112 dev-zero 1.4 <maintainer status="inactive">
113 ciaranm 1.2 <name>Foo Bar</name>
114     <email>foo@bar.bar</email>
115     </maintainer>
116 dev-zero 1.4 <maintainer status="active">
117     <name>Foo Gentoo</name>
118     <email>foo@gentoo.org</email>
119     </maintainer>
120 ciaranm 1.2 <changelog>http://foo.bar/changelog.txt</changelog>
121 dev-zero 1.4 <doc lang="en">http://foo.bar/doc/index.html</doc>
122 dev-zero 1.5 <doc lang="de">http://foo.bar/doc/index.de.html</doc>
123 ciaranm 1.2 <bugs-to>https://bugs.foo.bar</bugs-to>
124 dev-zero 1.4 <remote-id type="freshmeat">foobar</remote-id>
125 ciaranm 1.2 <remote-id type="sourceforge">foobar</remote-id>
126 ciaranm 1.1 </upstream>
127    
128    
129     Backwards Compatibility
130     =======================
131    
132 ciaranm 1.2 No changes are necessary to existing ``metadata.xml`` files. Information
133 dev-zero 1.4 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 ciaranm 1.1
137 dev-zero 1.5 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).
144    
145    
146 ciaranm 1.1 Copyright
147     =========
148    
149     This document has been placed in the public domain.
150    
151 ciaranm 1.2 .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20