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.4 $ |
3 | Version: $Revision: 1.6 $ |
4 | Last-Modified: $Date: 2008/01/24 13:00:09 $ |
4 | Last-Modified: $Date: 2008/05/10 07:50:43 $ |
5 | Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org> |
5 | Author: Marcelo Goes <vanquirius@gentoo.org>, Ciaran McCreesh <ciaranm@gentoo.org>, Tiziano Müller <dev-zero@gentoo.org> |
6 | Status: Deferred |
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 | Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008, 10-May-2008 |
11 | |
11 | |
12 | Abstract |
12 | Abstract |
13 | ======== |
13 | ======== |
14 | |
14 | |
15 | Tree ``metadata.xml`` files are currently used to specify maintainer and |
15 | Tree ``metadata.xml`` files are currently used to specify maintainer and |
… | |
… | |
75 | ``name`` should contain a block of text with upstream's name, is mandatory |
75 | ``name`` should contain a block of text with upstream's name, is mandatory |
76 | and can only appear once. |
76 | and can only appear once. |
77 | |
77 | |
78 | ``email`` should contain an e-mail address in the format ``foo@bar.bar``. |
78 | ``email`` should contain an e-mail address in the format ``foo@bar.bar``. |
79 | |
79 | |
80 | ``changelog`` should contain a URL prefixed with ``http://`` or |
80 | ``changelog`` should contain a URL where the location of the upstream |
81 | ``https://`` where the location of the upstream changelog can be found. |
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.) |
82 | |
85 | |
83 | ``doc`` should contain a URL prefixed with with ``http://`` or |
86 | ``doc`` should contain a URL where the location of the upstream |
84 | ``https://`` where the location of the upstream documentation can be found. |
87 | documentation can be found. The link must not point to any third party |
85 | The link must not point to any third party documentation and must be version |
88 | documentation and must be version independent. If the documentation is |
86 | independent. If the documentation is available in more than one language, a |
89 | available in more than one language, a ``lang`` attribute can be used |
87 | ``lang`` attribute can be used which follows the same rules as the one |
90 | which follows the same rules as the one for ``longdescription``. |
88 | for ``longdescription``. |
|
|
89 | |
91 | |
90 | ``bugs-to`` should contain a place where bugs can be filed, a URL |
92 | ``bugs-to`` should contain a place where bugs can be filed, a URL or an |
91 | prefixed with ``http://`` or ``https://`` or an e-mail address prefixed |
93 | e-mail address prefixed with ``mailto:``. |
92 | with ``mailto:``. |
|
|
93 | |
94 | |
94 | ``remote-id`` should specify a type of package identification tracker |
95 | ``remote-id`` should specify a type of package identification tracker |
95 | and the identification that corresponds to the package in question. |
96 | and the identification that corresponds to the package in question. |
96 | ``remote-id`` should make it easier to index information such as its |
97 | ``remote-id`` should make it easier to index information such as its |
97 | Freshmeat ID or its CPAN name. |
98 | Freshmeat ID or its CPAN name. |
… | |
… | |
101 | which case the element content should be the Freshmeat ID or ``vim``, in |
102 | 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 | 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 | identifier. This GLEP does not specify a complete list of legal values |
104 | for ``type`` -- developers should email the ``gentoo-dev`` mailing list |
105 | 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 | before using a new ``type`` value. The list of valid tags should be kept |
106 | in ``metadata/dtd/remote-id-tags.dtd``. |
107 | in ``metadata/dtd/remote-id-tags.dtd`` or ``metadata/dtd/metadata.dtd``. |
107 | |
108 | |
108 | For example, a ``metadata.xml`` upstream snippet may look like:: |
109 | For example, a ``metadata.xml`` upstream snippet may look like:: |
109 | |
110 | |
110 | <upstream> |
111 | <upstream> |
111 | <maintainer status="inactive"> |
112 | <maintainer status="inactive"> |
… | |
… | |
116 | <name>Foo Gentoo</name> |
117 | <name>Foo Gentoo</name> |
117 | <email>foo@gentoo.org</email> |
118 | <email>foo@gentoo.org</email> |
118 | </maintainer> |
119 | </maintainer> |
119 | <changelog>http://foo.bar/changelog.txt</changelog> |
120 | <changelog>http://foo.bar/changelog.txt</changelog> |
120 | <doc lang="en">http://foo.bar/doc/index.html</doc> |
121 | <doc lang="en">http://foo.bar/doc/index.html</doc> |
121 | <doc lang="de">http://foo.bar./doc/index.de.html</doc> |
122 | <doc lang="de">http://foo.bar/doc/index.de.html</doc> |
122 | <bugs-to>https://bugs.foo.bar</bugs-to> |
123 | <bugs-to>https://bugs.foo.bar</bugs-to> |
123 | <remote-id type="freshmeat">foobar</remote-id> |
124 | <remote-id type="freshmeat">foobar</remote-id> |
124 | <remote-id type="sourceforge">foobar</remote-id> |
125 | <remote-id type="sourceforge">foobar</remote-id> |
125 | </upstream> |
126 | </upstream> |
126 | |
127 | |
… | |
… | |
131 | No changes are necessary to existing ``metadata.xml`` files. Information |
132 | No changes are necessary to existing ``metadata.xml`` files. Information |
132 | in the new tags is not mandatory. Tools that currently read |
133 | in the new tags is not mandatory. Tools that currently read |
133 | ``metadata.xml`` files may break if written poorly; well written tools |
134 | ``metadata.xml`` files may break if written poorly; well written tools |
134 | should just ignore the additional elements. |
135 | should just ignore the additional elements. |
135 | |
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). |
|
|
144 | |
|
|
145 | |
136 | Copyright |
146 | Copyright |
137 | ========= |
147 | ========= |
138 | |
148 | |
139 | This document has been placed in the public domain. |
149 | This document has been placed in the public domain. |
140 | |
150 | |