/[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.2 - (hide annotations) (download)
Mon Mar 6 03:17:07 2006 UTC (8 years, 5 months ago) by ciaranm
Branch: MAIN
Changes since 1.1: +72 -41 lines
File MIME type: text/plain
glep 46 updates

1 ciaranm 1.1 GLEP: 46
2     Title: Allow upstream tags in metadata.xml
3 ciaranm 1.2 Version: $Revision: 1.1 $
4     Last-Modified: $Date: 2005/12/27 00:26:58 $
5     Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>
6 ciaranm 1.1 Status: Draft
7     Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 26-Dec-2005
10 ciaranm 1.2 Post-History: 26-Dec-2005, 5-Mar-2006
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     Specification
48     =============
49    
50 ciaranm 1.2 ``metadata.dtd`` should allow the use of a upstream tag in
51     ``metadata.xml``. Inside the upstream tag, developers should be able to
52     add upstream related information.
53 ciaranm 1.1
54     This GLEP defines the following four tags for ``upstream``:
55 ciaranm 1.2 ``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of
56     which are mandatory. Future GLEPs may extend this -- tools processing
57     metadata.xml should ignore unrecognized elements.
58    
59     ``maintainer`` can contain the tags ``name`` and ``email``, indicating
60     the person or organization responsible for upstream maintainership of
61     the package.
62 ciaranm 1.1
63     ``name`` should contain a block of text with upstream's name.
64    
65     ``email`` should contain an e-mail address in the format foo@bar.bar.
66    
67 ciaranm 1.2 ``changelog`` should contain a URL prefixed with ``http://`` or
68     ``https://`` where the location of the upstream changelog can be found.
69 ciaranm 1.1
70 ciaranm 1.2 ``bugs-to`` should contain a place where bugs can be filed, a URL
71     prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
72     with ``mailto:``.
73    
74     ``remote-id`` should specify a type of package identification tracker
75     and the identification that corresponds to the package in question.
76     ``remote-id`` should make it easier to index information such as its
77     Freshmeat ID or its CPAN name.
78    
79     The ``remote-id`` element has a ``type`` attribute, which is a string
80     identifying the type of upstream source. Examples are ``freshmeat``, in
81     which case the element content should be the Freshmeat ID or ``vim``, in
82     which case the element content should be the ``vim.org`` script
83     identifier. This GLEP does not specify a complete list of legal values
84     for ``type`` -- developers should email the ``gentoo-dev`` mailing list
85     before using a new ``type`` value.
86 ciaranm 1.1
87 ciaranm 1.2 For example, a ``metadata.xml`` upstream snippet may look like::
88 ciaranm 1.1
89     <upstream>
90 ciaranm 1.2 <maintainer>
91     <name>Foo Bar</name>
92     <email>foo@bar.bar</email>
93     </maintainer>
94     <changelog>http://foo.bar/changelog.txt</changelog>
95     <bugs-to>https://bugs.foo.bar</bugs-to>
96     <remote-id type="freshmeat">12345</remote-id>
97     <remote-id type="sourceforge">foobar</remote-id>
98 ciaranm 1.1 </upstream>
99    
100    
101     Backwards Compatibility
102     =======================
103    
104 ciaranm 1.2 No changes are necessary to existing ``metadata.xml`` files. Information
105     in the new tags is not be mandatory. Any sane tool that currently
106     handles ``metadata.xml`` files will simply ignore unrecognised elements.
107 ciaranm 1.1
108     Copyright
109     =========
110    
111     This document has been placed in the public domain.
112    
113 ciaranm 1.2 .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20