Gentoo Archives: gentoo-commits

From: "Tiziano Mueller (dev-zero)" <dev-zero@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/glep: glep-0046.html glep-0046.txt
Date: Thu, 24 Jan 2008 13:00:13
Message-Id: E1JI1gf-0003B3-KS@stork.gentoo.org
1 dev-zero 08/01/24 13:00:09
2
3 Modified: glep-0046.html glep-0046.txt
4 Log:
5 Updated glep-0046 according to the discussion on the gentoo.devel mailinglist
6
7 Revision Changes Path
8 1.7 xml/htdocs/proj/en/glep/glep-0046.html
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.html?rev=1.7&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.html?rev=1.7&content-type=text/plain
12 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.html?r1=1.6&r2=1.7
13
14 Index: glep-0046.html
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/glep/glep-0046.html,v
17 retrieving revision 1.6
18 retrieving revision 1.7
19 diff -u -r1.6 -r1.7
20 --- glep-0046.html 14 Oct 2007 17:00:15 -0000 1.6
21 +++ glep-0046.html 24 Jan 2008 13:00:09 -0000 1.7
22 @@ -32,7 +32,7 @@
23 </tr>
24 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0046.txt?cvsroot=gentoo">2007/04/21 03:13:16</a></td>
25 </tr>
26 -<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcelo Goes &lt;vanquirius&#32;&#97;t&#32;gentoo.org&gt;, Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;</td>
27 +<tr class="field"><th class="field-name">Author:</th><td class="field-body">Marcelo Goes &lt;vanquirius&#32;&#97;t&#32;gentoo.org&gt;, Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;, Tiziano Müller &lt;dev-zero&#32;&#97;t&#32;gentoo.org&gt;</td>
28 </tr>
29 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Deferred</td>
30 </tr>
31 @@ -42,7 +42,7 @@
32 </tr>
33 <tr class="field"><th class="field-name">Created:</th><td class="field-body">26-Dec-2005</td>
34 </tr>
35 -<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Dec-2005, 5-Mar-2006</td>
36 +<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Dec-2005, 5-Mar-2006, 24-Jan-2008</td>
37 </tr>
38 </tbody>
39 </table>
40 @@ -85,6 +85,8 @@
41 useful information to end users.</li>
42 <li>It will reduce the time spent by developers trying to find how to
43 contact upstream.</li>
44 +<li>It will give treecleaners additional information to decide whether
45 +a package can be removed from the tree.</li>
46 </ul>
47 </div>
48 <div class="section">
49 @@ -92,17 +94,31 @@
50 <p><tt class="docutils literal"><span class="pre">metadata.dtd</span></tt> should allow the use of a upstream tag in
51 <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>. Inside the upstream tag, developers should be able to
52 add upstream related information.</p>
53 -<p>This GLEP defines the following four tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
54 -<tt class="docutils literal"><span class="pre">maintainer</span></tt>, <tt class="docutils literal"><span class="pre">changelog</span></tt>, <tt class="docutils literal"><span class="pre">bugs-to</span></tt> and <tt class="docutils literal"><span class="pre">remote-id</span></tt>, none of
55 +<p>This GLEP defines the following five tags for <tt class="docutils literal"><span class="pre">upstream</span></tt>:
56 +<tt class="docutils literal"><span class="pre">maintainer</span></tt>, <tt class="docutils literal"><span class="pre">changelog</span></tt>, <tt class="docutils literal"><span class="pre">bugs-to</span></tt>, <tt class="docutils literal"><span class="pre">remote-id</span></tt> and <tt class="docutils literal"><span class="pre">doc</span></tt> none of
57 which are mandatory. Future GLEPs may extend this -- tools processing
58 metadata.xml should ignore unrecognized elements.</p>
59 <p><tt class="docutils literal"><span class="pre">maintainer</span></tt> can contain the tags <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">email</span></tt>, indicating
60 the person or organization responsible for upstream maintainership of
61 -the package.</p>
62 -<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name.</p>
63 -<p><tt class="docutils literal"><span class="pre">email</span></tt> should contain an e-mail address in the format <a class="reference" href="mailto:foo&#64;bar.bar">foo&#64;bar.bar</a>.</p>
64 +the package. The tag may appear more than once.</p>
65 +<p>The <tt class="docutils literal"><span class="pre">maintainer</span></tt> element has a <tt class="docutils literal"><span class="pre">status</span></tt> attribute, which is one of
66 +<tt class="docutils literal"><span class="pre">active</span></tt> or <tt class="docutils literal"><span class="pre">inactive</span></tt>. This attribute is not mandatory. The absence of it
67 +shall be interpreted as <tt class="docutils literal"><span class="pre">unknown</span></tt>.</p>
68 +<p>The <tt class="docutils literal"><span class="pre">maintainer</span></tt> element can be the same as the top-level <tt class="docutils literal"><span class="pre">maintainer</span></tt>
69 +element in cases where a developer decides to maintain the package in
70 +addition to/instead of the original upstream. In such cases a <tt class="docutils literal"><span class="pre">maintainer</span></tt>
71 +entry for the original upstream should be present.</p>
72 +<p><tt class="docutils literal"><span class="pre">name</span></tt> should contain a block of text with upstream's name, is mandatory
73 +and can only appear once.</p>
74 +<p><tt class="docutils literal"><span class="pre">email</span></tt> should contain an e-mail address in the format <tt class="docutils literal"><span class="pre">foo&#64;bar.bar</span></tt>.</p>
75 <p><tt class="docutils literal"><span class="pre">changelog</span></tt> should contain a URL prefixed with <tt class="docutils literal"><span class="pre">http://</span></tt> or
76 <tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream changelog can be found.</p>
77 +<p><tt class="docutils literal"><span class="pre">doc</span></tt> should contain a URL prefixed with with <tt class="docutils literal"><span class="pre">http://</span></tt> or
78 +<tt class="docutils literal"><span class="pre">https://</span></tt> where the location of the upstream documentation can be found.
79 +The link must not point to any third party documentation and must be version
80 +independent. If the documentation is available in more than one language, a
81 +<tt class="docutils literal"><span class="pre">lang</span></tt> attribute can be used which follows the same rules as the one
82 +for <tt class="docutils literal"><span class="pre">longdescription</span></tt>.</p>
83 <p><tt class="docutils literal"><span class="pre">bugs-to</span></tt> should contain a place where bugs can be filed, a URL
84 prefixed with <tt class="docutils literal"><span class="pre">http://</span></tt> or <tt class="docutils literal"><span class="pre">https://</span></tt> or an e-mail address prefixed
85 with <tt class="docutils literal"><span class="pre">mailto:</span></tt>.</p>
86 @@ -116,17 +132,24 @@
87 which case the element content should be the <tt class="docutils literal"><span class="pre">vim.org</span></tt> script
88 identifier. This GLEP does not specify a complete list of legal values
89 for <tt class="docutils literal"><span class="pre">type</span></tt> -- developers should email the <tt class="docutils literal"><span class="pre">gentoo-dev</span></tt> mailing list
90 -before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value.</p>
91 +before using a new <tt class="docutils literal"><span class="pre">type</span></tt> value. The list of valid tags should be kept
92 +in <tt class="docutils literal"><span class="pre">metadata/dtd/remote-id-tags.dtd</span></tt>.</p>
93 <p>For example, a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> upstream snippet may look like:</p>
94 <pre class="literal-block">
95 &lt;upstream&gt;
96 - &lt;maintainer&gt;
97 + &lt;maintainer status=&quot;inactive&quot;&gt;
98 &lt;name&gt;Foo Bar&lt;/name&gt;
99 &lt;email&gt;foo&#64;bar.bar&lt;/email&gt;
100 &lt;/maintainer&gt;
101 + &lt;maintainer status=&quot;active&quot;&gt;
102 + &lt;name&gt;Foo Gentoo&lt;/name&gt;
103 + &lt;email&gt;foo&#64;gentoo.org&lt;/email&gt;
104 + &lt;/maintainer&gt;
105 &lt;changelog&gt;http://foo.bar/changelog.txt&lt;/changelog&gt;
106 + &lt;doc lang=&quot;en&quot;&gt;http://foo.bar/doc/index.html&lt;/doc&gt;
107 + &lt;doc lang=&quot;de&quot;&gt;http://foo.bar./doc/index.de.html&lt;/doc&gt;
108 &lt;bugs-to&gt;https://bugs.foo.bar&lt;/bugs-to&gt;
109 - &lt;remote-id type=&quot;freshmeat&quot;&gt;12345&lt;/remote-id&gt;
110 + &lt;remote-id type=&quot;freshmeat&quot;&gt;foobar&lt;/remote-id&gt;
111 &lt;remote-id type=&quot;sourceforge&quot;&gt;foobar&lt;/remote-id&gt;
112 &lt;/upstream&gt;
113 </pre>
114 @@ -134,8 +157,9 @@
115 <div class="section">
116 <h1><a class="toc-backref" href="#id5" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
117 <p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information
118 -in the new tags is not be mandatory. Any sane tool that currently
119 -handles <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files will simply ignore unrecognised elements.</p>
120 +in the new tags is not mandatory. Tools that currently read
121 +<tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files may break if written poorly; well written tools
122 +should just ignore the additional elements.</p>
123 </div>
124 <div class="section">
125 <h1><a class="toc-backref" href="#id6" id="copyright" name="copyright">Copyright</a></h1>
126 @@ -147,7 +171,7 @@
127 <div class="footer">
128 <hr class="footer" />
129 <a class="reference" href="glep-0046.txt">View document source</a>.
130 -Generated on: 2007-10-13 13:39 UTC.
131 +Generated on: 2008-01-24 12:57 UTC.
132 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
133
134 </div>
135
136
137
138 1.4 xml/htdocs/proj/en/glep/glep-0046.txt
139
140 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.txt?rev=1.4&view=markup
141 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.txt?rev=1.4&content-type=text/plain
142 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0046.txt?r1=1.3&r2=1.4
143
144 Index: glep-0046.txt
145 ===================================================================
146 RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/glep/glep-0046.txt,v
147 retrieving revision 1.3
148 retrieving revision 1.4
149 diff -u -r1.3 -r1.4
150 --- glep-0046.txt 21 Apr 2007 03:13:16 -0000 1.3
151 +++ glep-0046.txt 24 Jan 2008 13:00:09 -0000 1.4
152 @@ -1,13 +1,13 @@
153 GLEP: 46
154 Title: Allow upstream tags in metadata.xml
155 -Version: $Revision: 1.3 $
156 -Last-Modified: $Date: 2007/04/21 03:13:16 $
157 -Author: Marcelo Goes <vanquirius@g.o>, Ciaran McCreesh <ciaranm@g.o>
158 +Version: $Revision: 1.4 $
159 +Last-Modified: $Date: 2008/01/24 13:00:09 $
160 +Author: Marcelo Goes <vanquirius@g.o>, Ciaran McCreesh <ciaranm@g.o>, Tiziano Müller <dev-zero@g.o>
161 Status: Deferred
162 Type: Standards Track
163 Content-Type: text/x-rst
164 Created: 26-Dec-2005
165 -Post-History: 26-Dec-2005, 5-Mar-2006
166 +Post-History: 26-Dec-2005, 5-Mar-2006, 24-Jan-2008
167
168 Abstract
169 ========
170 @@ -44,6 +44,9 @@
171 * It will reduce the time spent by developers trying to find how to
172 contact upstream.
173
174 +* It will give treecleaners additional information to decide whether
175 + a package can be removed from the tree.
176 +
177 Specification
178 =============
179
180 @@ -51,22 +54,39 @@
181 ``metadata.xml``. Inside the upstream tag, developers should be able to
182 add upstream related information.
183
184 -This GLEP defines the following four tags for ``upstream``:
185 -``maintainer``, ``changelog``, ``bugs-to`` and ``remote-id``, none of
186 +This GLEP defines the following five tags for ``upstream``:
187 +``maintainer``, ``changelog``, ``bugs-to``, ``remote-id`` and ``doc`` none of
188 which are mandatory. Future GLEPs may extend this -- tools processing
189 metadata.xml should ignore unrecognized elements.
190
191 ``maintainer`` can contain the tags ``name`` and ``email``, indicating
192 the person or organization responsible for upstream maintainership of
193 -the package.
194 +the package. The tag may appear more than once.
195 +
196 +The ``maintainer`` element has a ``status`` attribute, which is one of
197 +``active`` or ``inactive``. This attribute is not mandatory. The absence of it
198 +shall be interpreted as ``unknown``.
199 +
200 +The ``maintainer`` element can be the same as the top-level ``maintainer``
201 +element in cases where a developer decides to maintain the package in
202 +addition to/instead of the original upstream. In such cases a ``maintainer``
203 +entry for the original upstream should be present.
204
205 -``name`` should contain a block of text with upstream's name.
206 +``name`` should contain a block of text with upstream's name, is mandatory
207 +and can only appear once.
208
209 -``email`` should contain an e-mail address in the format foo@×××.bar.
210 +``email`` should contain an e-mail address in the format ``foo@×××.bar``.
211
212 ``changelog`` should contain a URL prefixed with ``http://`` or
213 ``https://`` where the location of the upstream changelog can be found.
214
215 +``doc`` should contain a URL prefixed with with ``http://`` or
216 +``https://`` where the location of the upstream documentation can be found.
217 +The link must not point to any third party documentation and must be version
218 +independent. If the documentation is available in more than one language, a
219 +``lang`` attribute can be used which follows the same rules as the one
220 +for ``longdescription``.
221 +
222 ``bugs-to`` should contain a place where bugs can be filed, a URL
223 prefixed with ``http://`` or ``https://`` or an e-mail address prefixed
224 with ``mailto:``.
225 @@ -82,18 +102,25 @@
226 which case the element content should be the ``vim.org`` script
227 identifier. This GLEP does not specify a complete list of legal values
228 for ``type`` -- developers should email the ``gentoo-dev`` mailing list
229 -before using a new ``type`` value.
230 +before using a new ``type`` value. The list of valid tags should be kept
231 +in ``metadata/dtd/remote-id-tags.dtd``.
232
233 For example, a ``metadata.xml`` upstream snippet may look like::
234
235 <upstream>
236 - <maintainer>
237 + <maintainer status="inactive">
238 <name>Foo Bar</name>
239 <email>foo@×××.bar</email>
240 </maintainer>
241 + <maintainer status="active">
242 + <name>Foo Gentoo</name>
243 + <email>foo@g.o</email>
244 + </maintainer>
245 <changelog>http://foo.bar/changelog.txt</changelog>
246 + <doc lang="en">http://foo.bar/doc/index.html</doc>
247 + <doc lang="de">http://foo.bar./doc/index.de.html</doc>
248 <bugs-to>https://bugs.foo.bar</bugs-to>
249 - <remote-id type="freshmeat">12345</remote-id>
250 + <remote-id type="freshmeat">foobar</remote-id>
251 <remote-id type="sourceforge">foobar</remote-id>
252 </upstream>
253
254 @@ -102,8 +129,9 @@
255 =======================
256
257 No changes are necessary to existing ``metadata.xml`` files. Information
258 -in the new tags is not be mandatory. Any sane tool that currently
259 -handles ``metadata.xml`` files will simply ignore unrecognised elements.
260 +in the new tags is not mandatory. Tools that currently read
261 +``metadata.xml`` files may break if written poorly; well written tools
262 +should just ignore the additional elements.
263
264 Copyright
265 =========
266
267
268
269 --
270 gentoo-commits@l.g.o mailing list