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

1 GLEP: 46
2 Title: Allow upstream tags in metadata.xml
3 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 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 26-Dec-2005
10 Post-History: 26-Dec-2005, 5-Mar-2006
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 Specification
48 =============
49
50 ``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
54 This GLEP defines the following four tags for ``upstream``:
55 ``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
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 ``changelog`` should contain a URL prefixed with ``http://`` or
68 ``https://`` where the location of the upstream changelog can be found.
69
70 ``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
87 For example, a ``metadata.xml`` upstream snippet may look like::
88
89 <upstream>
90 <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 </upstream>
99
100
101 Backwards Compatibility
102 =======================
103
104 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
108 Copyright
109 =========
110
111 This document has been placed in the public domain.
112
113 .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20