chiark / gitweb /
c8dfe625dad7c9b203c93960545ad14deacb5475
[developers-reference.git] / po4a / po / developers-reference.pot
1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
5 #
6 #, fuzzy
7 msgid ""
8 msgstr ""
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2012-06-28 05:40-0400\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
14 "Language: \n"
15 "MIME-Version: 1.0\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
18
19 #. type: Content of: <chapter><title>
20 #: best-pkging-practices.dbk:7
21 msgid "Best Packaging Practices"
22 msgstr ""
23
24 #. type: Content of: <chapter><para>
25 #: best-pkging-practices.dbk:9
26 msgid ""
27 "Debian's quality is largely due to the <ulink "
28 "url=\"&url-debian-policy;\">Debian Policy</ulink>, which defines explicit "
29 "baseline requirements which all Debian packages must fulfill.  Yet there is "
30 "also a shared history of experience which goes beyond the Debian Policy, an "
31 "accumulation of years of experience in packaging.  Many very talented people "
32 "have created great tools, tools which help you, the Debian maintainer, "
33 "create and maintain excellent packages."
34 msgstr ""
35
36 #. type: Content of: <chapter><para>
37 #: best-pkging-practices.dbk:18
38 msgid ""
39 "This chapter provides some best practices for Debian developers.  All "
40 "recommendations are merely that, and are not requirements or policy.  These "
41 "are just some subjective hints, advice and pointers collected from Debian "
42 "developers.  Feel free to pick and choose whatever works best for you."
43 msgstr ""
44
45 #. type: Content of: <chapter><section><title>
46 #: best-pkging-practices.dbk:24
47 msgid "Best practices for <filename>debian/rules</filename>"
48 msgstr ""
49
50 #. type: Content of: <chapter><section><para>
51 #: best-pkging-practices.dbk:26
52 msgid ""
53 "The following recommendations apply to the <filename>debian/rules</filename> "
54 "file.  Since <filename>debian/rules</filename> controls the build process "
55 "and selects the files which go into the package (directly or indirectly), "
56 "it's usually the file maintainers spend the most time on."
57 msgstr ""
58
59 #. type: Content of: <chapter><section><section><title>
60 #: best-pkging-practices.dbk:32
61 msgid "Helper scripts"
62 msgstr ""
63
64 #. type: Content of: <chapter><section><section><para>
65 #: best-pkging-practices.dbk:34
66 msgid ""
67 "The rationale for using helper scripts in <filename>debian/rules</filename> "
68 "is that they let maintainers use and share common logic among many "
69 "packages.  Take for instance the question of installing menu entries: you "
70 "need to put the file into <filename>/usr/share/menu</filename> (or "
71 "<filename>/usr/lib/menu</filename> for executable binary menufiles, if this "
72 "is needed), and add commands to the maintainer scripts to register and "
73 "unregister the menu entries.  Since this is a very common thing for packages "
74 "to do, why should each maintainer rewrite all this on their own, sometimes "
75 "with bugs? Also, supposing the menu directory changed, every package would "
76 "have to be changed."
77 msgstr ""
78
79 #. type: Content of: <chapter><section><section><para>
80 #: best-pkging-practices.dbk:45
81 msgid ""
82 "Helper scripts take care of these issues.  Assuming you comply with the "
83 "conventions expected by the helper script, the helper takes care of all the "
84 "details.  Changes in policy can be made in the helper script; then packages "
85 "just need to be rebuilt with the new version of the helper and no other "
86 "changes."
87 msgstr ""
88
89 #. type: Content of: <chapter><section><section><para>
90 #: best-pkging-practices.dbk:52
91 msgid ""
92 "<xref linkend=\"tools\"/> contains a couple of different helpers.  The most "
93 "common and best (in our opinion) helper system is <systemitem "
94 "role=\"package\">debhelper</systemitem>.  Previous helper systems, such as "
95 "<systemitem role=\"package\">debmake</systemitem>, were monolithic: you "
96 "couldn't pick and choose which part of the helper you found useful, but had "
97 "to use the helper to do everything.  <systemitem "
98 "role=\"package\">debhelper</systemitem>, however, is a number of separate "
99 "little <command>dh_*</command> programs.  For instance, "
100 "<command>dh_installman</command> installs and compresses man pages, "
101 "<command>dh_installmenu</command> installs menu files, and so on.  Thus, it "
102 "offers enough flexibility to be able to use the little helper scripts, where "
103 "useful, in conjunction with hand-crafted commands in "
104 "<filename>debian/rules</filename>."
105 msgstr ""
106
107 #. type: Content of: <chapter><section><section><para>
108 #: best-pkging-practices.dbk:66
109 msgid ""
110 "You can get started with <systemitem role=\"package\">debhelper</systemitem> "
111 "by reading <citerefentry> <refentrytitle>debhelper</refentrytitle> "
112 "<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that "
113 "come with the package.  <command>dh_make</command>, from the <systemitem "
114 "role=\"package\">dh-make</systemitem> package (see <xref "
115 "linkend=\"dh-make\"/>), can be used to convert a vanilla source package to a "
116 "<systemitem role=\"package\">debhelper</systemitem>ized package.  This "
117 "shortcut, though, should not convince you that you do not need to bother "
118 "understanding the individual <command>dh_*</command> helpers.  If you are "
119 "going to use a helper, you do need to take the time to learn to use that "
120 "helper, to learn its expectations and behavior."
121 msgstr ""
122
123 #. type: Content of: <chapter><section><section><para>
124 #: best-pkging-practices.dbk:79
125 msgid ""
126 "Some people feel that vanilla <filename>debian/rules</filename> files are "
127 "better, since you don't have to learn the intricacies of any helper system.  "
128 "This decision is completely up to you.  Use what works for you.  Many "
129 "examples of vanilla <filename>debian/rules</filename> files are available at "
130 "<ulink url=\"&url-rules-files;\"></ulink>."
131 msgstr ""
132
133 #. type: Content of: <chapter><section><section><title>
134 #: best-pkging-practices.dbk:88
135 msgid "Separating your patches into multiple files"
136 msgstr ""
137
138 #. type: Content of: <chapter><section><section><para>
139 #: best-pkging-practices.dbk:90
140 msgid ""
141 "Big, complex packages may have many bugs that you need to deal with.  If you "
142 "correct a number of bugs directly in the source, and you're not careful, it "
143 "can get hard to differentiate the various patches that you applied.  It can "
144 "get quite messy when you have to update the package to a new upstream "
145 "version which integrates some of the fixes (but not all).  You can't take "
146 "the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
147 "out which patch sets to back out as a unit as bugs are fixed upstream."
148 msgstr ""
149
150 #. type: Content of: <chapter><section><section><para>
151 #: best-pkging-practices.dbk:99
152 msgid ""
153 "Fortunately, with the source format “3.0 (quilt)” it is now possible to keep "
154 "patches separate without having to modify <filename>debian/rules</filename> "
155 "to setup a patch system. Patches are stored in "
156 "<filename>debian/patches/</filename> and when the source package is unpacked "
157 "patches listed in <filename>debian/patches/series</filename> are "
158 "automatically applied.  As the name implies, patches can be managed with "
159 "<command>quilt</command>."
160 msgstr ""
161
162 #. type: Content of: <chapter><section><section><para>
163 #: best-pkging-practices.dbk:107
164 msgid ""
165 "When using the older source “1.0”, it's also possible to separate patches "
166 "but a dedicated patch system must be used: the patch files are shipped "
167 "within the Debian patch file (<filename>.diff.gz</filename>), usually within "
168 "the <filename>debian/</filename> directory. The only difference is that they "
169 "aren't applied immediately by <command>dpkg-source</command>, but by the "
170 "<literal>build</literal> rule of <filename>debian/rules</filename>, through "
171 "a dependency on the <literal>patch</literal> rule.  Conversely, they are "
172 "reverted in the <literal>clean</literal> rule, through a dependency on the "
173 "<literal>unpatch</literal> rule."
174 msgstr ""
175
176 #. type: Content of: <chapter><section><section><para>
177 #: best-pkging-practices.dbk:119
178 msgid ""
179 "<command>quilt</command> is the recommended tool for this.  It does all of "
180 "the above, and also allows to manage patch series.  See the <systemitem "
181 "role=\"package\">quilt</systemitem> package for more information."
182 msgstr ""
183
184 #. type: Content of: <chapter><section><section><para>
185 #: best-pkging-practices.dbk:125
186 msgid ""
187 "There are other tools to manage patches, like <command>dpatch</command>, and "
188 "the patch system integrated with <systemitem "
189 "role=\"package\">cdbs</systemitem>."
190 msgstr ""
191
192 #. type: Content of: <chapter><section><section><title>
193 #: best-pkging-practices.dbk:132
194 msgid "Multiple binary packages"
195 msgstr ""
196
197 #. type: Content of: <chapter><section><section><para>
198 #: best-pkging-practices.dbk:134
199 msgid ""
200 "A single source package will often build several binary packages, either to "
201 "provide several flavors of the same software (e.g., the <systemitem "
202 "role=\"package\">vim</systemitem> source package) or to make several small "
203 "packages instead of a big one (e.g., so the user can install only the subset "
204 "needed, and thus save some disk space)."
205 msgstr ""
206
207 #. type: Content of: <chapter><section><section><para>
208 #: best-pkging-practices.dbk:141
209 msgid ""
210 "The second case can be easily managed in <filename>debian/rules</filename>.  "
211 "You just need to move the appropriate files from the build directory into "
212 "the package's temporary trees.  You can do this using "
213 "<command>install</command> or <command>dh_install</command> from <systemitem "
214 "role=\"package\">debhelper</systemitem>.  Be sure to check the different "
215 "permutations of the various packages, ensuring that you have the "
216 "inter-package dependencies set right in <filename>debian/control</filename>."
217 msgstr ""
218
219 #. type: Content of: <chapter><section><section><para>
220 #: best-pkging-practices.dbk:150
221 msgid ""
222 "The first case is a bit more difficult since it involves multiple recompiles "
223 "of the same software but with different configuration options.  The "
224 "<systemitem role=\"package\">vim</systemitem> source package is an example "
225 "of how to manage this using an hand-crafted "
226 "<filename>debian/rules</filename> file."
227 msgstr ""
228
229 #. type: Content of: <chapter><section><title>
230 #: best-pkging-practices.dbk:162
231 msgid "Best practices for <filename>debian/control</filename>"
232 msgstr ""
233
234 #. type: Content of: <chapter><section><para>
235 #: best-pkging-practices.dbk:164
236 msgid ""
237 "The following practices are relevant to the "
238 "<filename>debian/control</filename> file.  They supplement the <ulink "
239 "url=\"&url-debian-policy;ch-binary.html#s-descriptions\">Policy on package "
240 "descriptions</ulink>."
241 msgstr ""
242
243 #. type: Content of: <chapter><section><para>
244 #: best-pkging-practices.dbk:170
245 msgid ""
246 "The description of the package, as defined by the corresponding field in the "
247 "<filename>control</filename> file, contains both the package synopsis and "
248 "the long description for the package.  <xref linkend=\"bpp-desc-basics\"/> "
249 "describes common guidelines for both parts of the package description.  "
250 "Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
251 "specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
252 "guidelines specific to the description."
253 msgstr ""
254
255 #. type: Content of: <chapter><section><section><title>
256 #: best-pkging-practices.dbk:179
257 msgid "General guidelines for package descriptions"
258 msgstr ""
259
260 #. type: Content of: <chapter><section><section><para>
261 #: best-pkging-practices.dbk:181
262 msgid ""
263 "The package description should be written for the average likely user, the "
264 "average person who will use and benefit from the package.  For instance, "
265 "development packages are for developers, and can be technical in their "
266 "language.  More general-purpose applications, such as editors, should be "
267 "written for a less technical user."
268 msgstr ""
269
270 #. type: Content of: <chapter><section><section><para>
271 #: best-pkging-practices.dbk:188
272 msgid ""
273 "Our review of package descriptions lead us to conclude that most package "
274 "descriptions are technical, that is, are not written to make sense for "
275 "non-technical users.  Unless your package really is only for technical "
276 "users, this is a problem."
277 msgstr ""
278
279 #. type: Content of: <chapter><section><section><para>
280 #: best-pkging-practices.dbk:194
281 msgid ""
282 "How do you write for non-technical users? Avoid jargon.  Avoid referring to "
283 "other applications or frameworks that the user might not be familiar with — "
284 "GNOME or KDE is fine, since users are probably familiar with these terms, "
285 "but GTK+ is probably not.  Try not to assume any knowledge at all.  If you "
286 "must use technical terms, introduce them."
287 msgstr ""
288
289 #. type: Content of: <chapter><section><section><para>
290 #: best-pkging-practices.dbk:201
291 msgid ""
292 "Be objective.  Package descriptions are not the place for advocating your "
293 "package, no matter how much you love it.  Remember that the reader may not "
294 "care about the same things you care about."
295 msgstr ""
296
297 #. type: Content of: <chapter><section><section><para>
298 #: best-pkging-practices.dbk:206
299 msgid ""
300 "References to the names of any other software packages, protocol names, "
301 "standards, or specifications should use their canonical forms, if one "
302 "exists.  For example, use X Window System, X11, or X; not X Windows, "
303 "X-Windows, or X Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  "
304 "Use PostScript, not Postscript or postscript."
305 msgstr ""
306
307 #. type: Content of: <chapter><section><section><para>
308 #: best-pkging-practices.dbk:213
309 msgid ""
310 "If you are having problems writing your description, you may wish to send it "
311 "along to &email-debian-l10n-english; and request feedback."
312 msgstr ""
313
314 #. type: Content of: <chapter><section><section><title>
315 #: best-pkging-practices.dbk:219
316 msgid "The package synopsis, or short description"
317 msgstr ""
318
319 #. type: Content of: <chapter><section><section><para>
320 #: best-pkging-practices.dbk:221
321 msgid ""
322 "Policy says the synopsis line (the short description) must be concise, not "
323 "repeating the package name, but also informative."
324 msgstr ""
325
326 #. type: Content of: <chapter><section><section><para>
327 #: best-pkging-practices.dbk:225
328 msgid ""
329 "The synopsis functions as a phrase describing the package, not a complete "
330 "sentence, so sentential punctuation is inappropriate: it does not need extra "
331 "capital letters or a final period (full stop). It should also omit any "
332 "initial indefinite or definite article — \"a\", \"an\", or \"the\". Thus for "
333 "instance:"
334 msgstr ""
335
336 #. type: Content of: <chapter><section><section><screen>
337 #: best-pkging-practices.dbk:231
338 #, no-wrap
339 msgid ""
340 "Package: libeg0\n"
341 "Description: exemplification support library\n"
342 msgstr ""
343
344 #. type: Content of: <chapter><section><section><para>
345 #: best-pkging-practices.dbk:235
346 msgid ""
347 "Technically this is a noun phrase minus articles, as opposed to a verb "
348 "phrase.  A good heuristic is that it should be possible to substitute the "
349 "package <replaceable>name</replaceable> and "
350 "<replaceable>synopsis</replaceable> into this formula:"
351 msgstr ""
352
353 #. type: Content of: <chapter><section><section><para>
354 #: best-pkging-practices.dbk:240
355 msgid ""
356 "The package <replaceable>name</replaceable> provides {a,an,the,some} "
357 "<replaceable>synopsis</replaceable>."
358 msgstr ""
359
360 #. type: Content of: <chapter><section><section><para>
361 #: best-pkging-practices.dbk:244
362 msgid ""
363 "Sets of related packages may use an alternative scheme that divides the "
364 "synopsis into two parts, the first a description of the whole suite and the "
365 "second a summary of the package's role within it:"
366 msgstr ""
367
368 #. type: Content of: <chapter><section><section><screen>
369 #: best-pkging-practices.dbk:249
370 #, no-wrap
371 msgid ""
372 "Package: eg-tools\n"
373 "Description: simple exemplification system (utilities)\n"
374 "\t\t\t              \n"
375 "Package: eg-doc\n"
376 "Description: simple exemplification system - documentation\n"
377 msgstr ""
378
379 #. type: Content of: <chapter><section><section><para>
380 #: best-pkging-practices.dbk:256
381 msgid ""
382 "These synopses follow a modified formula. Where a package "
383 "\"<replaceable>name</replaceable>\" has a synopsis "
384 "\"<replaceable>suite</replaceable> (<replaceable>role</replaceable>)\" or "
385 "\"<replaceable>suite</replaceable> - <replaceable>role</replaceable>\", the "
386 "elements should be phrased so that they fit into the formula:"
387 msgstr ""
388
389 #. type: Content of: <chapter><section><section><para>
390 #: best-pkging-practices.dbk:263
391 msgid ""
392 "The package <replaceable>name</replaceable> provides {a,an,the} "
393 "<replaceable>role</replaceable> for the <replaceable>suite</replaceable>."
394 msgstr ""
395
396 #. type: Content of: <chapter><section><section><title>
397 #: best-pkging-practices.dbk:269
398 msgid "The long description"
399 msgstr ""
400
401 #. type: Content of: <chapter><section><section><para>
402 #: best-pkging-practices.dbk:271
403 msgid ""
404 "The long description is the primary information available to the user about "
405 "a package before they install it.  It should provide all the information "
406 "needed to let the user decide whether to install the package.  Assume that "
407 "the user has already read the package synopsis."
408 msgstr ""
409
410 #. type: Content of: <chapter><section><section><para>
411 #: best-pkging-practices.dbk:277
412 msgid "The long description should consist of full and complete sentences."
413 msgstr ""
414
415 #. type: Content of: <chapter><section><section><para>
416 #: best-pkging-practices.dbk:280
417 msgid ""
418 "The first paragraph of the long description should answer the following "
419 "questions: what does the package do? what task does it help the user "
420 "accomplish? It is important to describe this in a non-technical way, unless "
421 "of course the audience for the package is necessarily technical."
422 msgstr ""
423
424 #. type: Content of: <chapter><section><section><para>
425 #: best-pkging-practices.dbk:286
426 msgid ""
427 "The following paragraphs should answer the following questions: Why do I as "
428 "a user need this package? What other features does the package have? What "
429 "outstanding features and deficiencies are there compared to other packages "
430 "(e.g., if you need X, use Y instead)? Is this package related to other "
431 "packages in some way that is not handled by the package manager (e.g., this "
432 "is the client for the foo server)?"
433 msgstr ""
434
435 #. type: Content of: <chapter><section><section><para>
436 #: best-pkging-practices.dbk:294
437 msgid ""
438 "Be careful to avoid spelling and grammar mistakes.  Ensure that you "
439 "spell-check it.  Both <command>ispell</command> and "
440 "<command>aspell</command> have special modes for checking "
441 "<filename>debian/control</filename> files:"
442 msgstr ""
443
444 #. type: Content of: <chapter><section><section><screen>
445 #: best-pkging-practices.dbk:299
446 #, no-wrap
447 msgid "ispell -d american -g debian/control\n"
448 msgstr ""
449
450 #. type: Content of: <chapter><section><section><screen>
451 #: best-pkging-practices.dbk:302
452 #, no-wrap
453 msgid "aspell -d en -D -c debian/control\n"
454 msgstr ""
455
456 #. type: Content of: <chapter><section><section><para>
457 #: best-pkging-practices.dbk:305
458 msgid ""
459 "Users usually expect these questions to be answered in the package "
460 "description:"
461 msgstr ""
462
463 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
464 #: best-pkging-practices.dbk:310
465 msgid ""
466 "What does the package do? If it is an add-on to another package, then the "
467 "short description of the package we are an add-on to should be put in here."
468 msgstr ""
469
470 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
471 #: best-pkging-practices.dbk:316
472 msgid ""
473 "Why should I want this package? This is related to the above, but not the "
474 "same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
475 "LDAP and IMAP, has features X, Y, and Z)."
476 msgstr ""
477
478 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
479 #: best-pkging-practices.dbk:323
480 msgid ""
481 "If this package should not be installed directly, but is pulled in by "
482 "another package, this should be mentioned."
483 msgstr ""
484
485 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
486 #: best-pkging-practices.dbk:329
487 msgid ""
488 "If the package is <literal>experimental</literal>, or there are other "
489 "reasons it should not be used, if there are other packages that should be "
490 "used instead, it should be here as well."
491 msgstr ""
492
493 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
494 #: best-pkging-practices.dbk:336
495 msgid ""
496 "How is this package different from the competition? Is it a better "
497 "implementation? more features? different features? Why should I choose this "
498 "package."
499 msgstr ""
500
501 #. type: Content of: <chapter><section><section><title>
502 #: best-pkging-practices.dbk:349
503 msgid "Upstream home page"
504 msgstr ""
505
506 #. type: Content of: <chapter><section><section><para>
507 #: best-pkging-practices.dbk:351
508 msgid ""
509 "We recommend that you add the URL for the package's home page in the "
510 "<literal>Homepage</literal> field of the <literal>Source</literal> section "
511 "in <filename>debian/control</filename>.  Adding this information in the "
512 "package description itself is considered deprecated."
513 msgstr ""
514
515 #. type: Content of: <chapter><section><section><title>
516 #: best-pkging-practices.dbk:359
517 msgid "Version Control System location"
518 msgstr ""
519
520 #. type: Content of: <chapter><section><section><para>
521 #: best-pkging-practices.dbk:361
522 msgid ""
523 "There are additional fields for the location of the Version Control System "
524 "in <filename>debian/control</filename>."
525 msgstr ""
526
527 #. type: Content of: <chapter><section><section><section><title>
528 #: best-pkging-practices.dbk:365
529 msgid "Vcs-Browser"
530 msgstr ""
531
532 #. type: Content of: <chapter><section><section><section><para>
533 #: best-pkging-practices.dbk:367
534 msgid ""
535 "Value of this field should be a <literal>http://</literal> URL pointing to a "
536 "web-browsable copy of the Version Control System repository used to maintain "
537 "the given package, if available."
538 msgstr ""
539
540 #. type: Content of: <chapter><section><section><section><para>
541 #: best-pkging-practices.dbk:372
542 msgid ""
543 "The information is meant to be useful for the final user, willing to browse "
544 "the latest work done on the package (e.g.  when looking for the patch fixing "
545 "a bug tagged as <literal>pending</literal> in the bug tracking system)."
546 msgstr ""
547
548 #. type: Content of: <chapter><section><section><section><title>
549 #: best-pkging-practices.dbk:379
550 msgid "Vcs-*"
551 msgstr ""
552
553 #. type: Content of: <chapter><section><section><section><para>
554 #: best-pkging-practices.dbk:381
555 msgid ""
556 "Value of this field should be a string identifying unequivocally the "
557 "location of the Version Control System repository used to maintain the given "
558 "package, if available.  <literal>*</literal> identify the Version Control "
559 "System; currently the following systems are supported by the package "
560 "tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
561 "<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
562 "<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
563 "<literal>svn</literal> (Subversion).  It is allowed to specify different VCS "
564 "fields for the same package: they will all be shown in the PTS web "
565 "interface."
566 msgstr ""
567
568 #. type: Content of: <chapter><section><section><section><para>
569 #: best-pkging-practices.dbk:392
570 msgid ""
571 "The information is meant to be useful for a user knowledgeable in the given "
572 "Version Control System and willing to build the current version of a package "
573 "from the VCS sources.  Other uses of this information might include "
574 "automatic building of the latest VCS version of the given package.  To this "
575 "end the location pointed to by the field should better be version agnostic "
576 "and point to the main branch (for VCSs supporting such a concept).  Also, "
577 "the location pointed to should be accessible to the final user; fulfilling "
578 "this requirement might imply pointing to an anonymous access of the "
579 "repository instead of pointing to an SSH-accessible version of the same."
580 msgstr ""
581
582 #. type: Content of: <chapter><section><section><section><para>
583 #: best-pkging-practices.dbk:403
584 msgid ""
585 "In the following example, an instance of the field for a Subversion "
586 "repository of the <systemitem role=\"package\">vim</systemitem> package is "
587 "shown.  Note how the URL is in the <literal>svn://</literal> scheme (instead "
588 "of <literal>svn+ssh://</literal>) and how it points to the "
589 "<filename>trunk/</filename> branch.  The use of the "
590 "<literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields "
591 "described above is also shown."
592 msgstr ""
593
594 #. type: Content of: <chapter><section><section><section><screen>
595 #: best-pkging-practices.dbk:412
596 #, no-wrap
597 msgid ""
598 "  Source: vim\n"
599 "  Section: editors\n"
600 "  Priority: optional\n"
601 "  &lt;snip&gt;\n"
602 "  Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
603 "  Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim\n"
604 "  Homepage: http://www.vim.org\n"
605 msgstr ""
606
607 #. type: Content of: <chapter><section><title>
608 #: best-pkging-practices.dbk:427
609 msgid "Best practices for <filename>debian/changelog</filename>"
610 msgstr ""
611
612 #. type: Content of: <chapter><section><para>
613 #: best-pkging-practices.dbk:429
614 msgid ""
615 "The following practices supplement the <ulink "
616 "url=\"&url-debian-policy;ch-docs.html#s-changelogs\">Policy on changelog "
617 "files</ulink>."
618 msgstr ""
619
620 #. type: Content of: <chapter><section><section><title>
621 #: best-pkging-practices.dbk:434
622 msgid "Writing useful changelog entries"
623 msgstr ""
624
625 #. type: Content of: <chapter><section><section><para>
626 #: best-pkging-practices.dbk:436
627 msgid ""
628 "The changelog entry for a package revision documents changes in that "
629 "revision, and only them.  Concentrate on describing significant and "
630 "user-visible changes that were made since the last version."
631 msgstr ""
632
633 #. type: Content of: <chapter><section><section><para>
634 #: best-pkging-practices.dbk:441
635 msgid ""
636 "Focus on <emphasis>what</emphasis> was changed — who, how and when are "
637 "usually less important.  Having said that, remember to politely attribute "
638 "people who have provided notable help in making the package (e.g., those who "
639 "have sent in patches)."
640 msgstr ""
641
642 #. type: Content of: <chapter><section><section><para>
643 #: best-pkging-practices.dbk:447
644 msgid ""
645 "There's no need to elaborate the trivial and obvious changes.  You can also "
646 "aggregate several changes in one entry.  On the other hand, don't be overly "
647 "terse if you have undertaken a major change.  Be especially clear if there "
648 "are changes that affect the behaviour of the program.  For further "
649 "explanations, use the <filename>README.Debian</filename> file."
650 msgstr ""
651
652 #. type: Content of: <chapter><section><section><para>
653 #: best-pkging-practices.dbk:454
654 msgid ""
655 "Use common English so that the majority of readers can comprehend it.  Avoid "
656 "abbreviations, tech-speak and jargon when explaining changes that close "
657 "bugs, especially for bugs filed by users that did not strike you as "
658 "particularly technically savvy.  Be polite, don't swear."
659 msgstr ""
660
661 #. type: Content of: <chapter><section><section><para>
662 #: best-pkging-practices.dbk:460
663 msgid ""
664 "It is sometimes desirable to prefix changelog entries with the names of the "
665 "files that were changed.  However, there's no need to explicitly list each "
666 "and every last one of the changed files, especially if the change was small "
667 "or repetitive.  You may use wildcards."
668 msgstr ""
669
670 #. type: Content of: <chapter><section><section><para>
671 #: best-pkging-practices.dbk:466
672 msgid ""
673 "When referring to bugs, don't assume anything.  Say what the problem was, "
674 "how it was fixed, and append the closes: #nnnnn string.  See <xref "
675 "linkend=\"upload-bugfix\"/> for more information."
676 msgstr ""
677
678 #. type: Content of: <chapter><section><section><title>
679 #: best-pkging-practices.dbk:473
680 msgid "Common misconceptions about changelog entries"
681 msgstr ""
682
683 #. type: Content of: <chapter><section><section><para>
684 #: best-pkging-practices.dbk:475
685 msgid ""
686 "The changelog entries should <emphasis role=\"strong\">not</emphasis> "
687 "document generic packaging issues (Hey, if you're looking for foo.conf, it's "
688 "in /etc/blah/.), since administrators and users are supposed to be at least "
689 "remotely acquainted with how such things are generally arranged on Debian "
690 "systems.  Do, however, mention if you change the location of a configuration "
691 "file."
692 msgstr ""
693
694 #. type: Content of: <chapter><section><section><para>
695 #: best-pkging-practices.dbk:483
696 msgid ""
697 "The only bugs closed with a changelog entry should be those that are "
698 "actually fixed in the same package revision.  Closing unrelated bugs in the "
699 "changelog is bad practice.  See <xref linkend=\"upload-bugfix\"/>."
700 msgstr ""
701
702 #. type: Content of: <chapter><section><section><para>
703 #: best-pkging-practices.dbk:488
704 msgid ""
705 "The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
706 "used for random discussion with bug reporters (I don't see segfaults when "
707 "starting foo with option bar; send in more info), general statements on "
708 "life, the universe and everything (sorry this upload took me so long, but I "
709 "caught the flu), or pleas for help (the bug list on this package is huge, "
710 "please lend me a hand).  Such things usually won't be noticed by their "
711 "target audience, but may annoy people who wish to read information about "
712 "actual changes in the package.  See <xref linkend=\"bug-answering\"/> for "
713 "more information on how to use the bug tracking system."
714 msgstr ""
715
716 #. type: Content of: <chapter><section><section><para>
717 #: best-pkging-practices.dbk:499
718 msgid ""
719 "It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
720 "in the first changelog entry of the proper maintainer upload.  As we have "
721 "version tracking now, it is enough to keep the NMUed changelog entries and "
722 "just mention this fact in your own changelog entry."
723 msgstr ""
724
725 #. type: Content of: <chapter><section><section><title>
726 #: best-pkging-practices.dbk:507
727 msgid "Common errors in changelog entries"
728 msgstr ""
729
730 #. type: Content of: <chapter><section><section><para>
731 #: best-pkging-practices.dbk:509
732 msgid ""
733 "The following examples demonstrate some common errors or examples of bad "
734 "style in changelog entries."
735 msgstr ""
736
737 #. type: Content of: <chapter><section><section><screen>
738 #: best-pkging-practices.dbk:513
739 #, no-wrap
740 msgid "  * Fixed all outstanding bugs.\n"
741 msgstr ""
742
743 #. type: Content of: <chapter><section><section><para>
744 #: best-pkging-practices.dbk:516
745 msgid "This doesn't tell readers anything too useful, obviously."
746 msgstr ""
747
748 #. type: Content of: <chapter><section><section><screen>
749 #: best-pkging-practices.dbk:519
750 #, no-wrap
751 msgid "  * Applied patch from Jane Random.\n"
752 msgstr ""
753
754 #. type: Content of: <chapter><section><section><para>
755 #: best-pkging-practices.dbk:522
756 msgid "What was the patch about?"
757 msgstr ""
758
759 #. type: Content of: <chapter><section><section><screen>
760 #: best-pkging-practices.dbk:525
761 #, no-wrap
762 msgid "  * Late night install target overhaul.\n"
763 msgstr ""
764
765 #. type: Content of: <chapter><section><section><para>
766 #: best-pkging-practices.dbk:528
767 msgid ""
768 "Overhaul which accomplished what? Is the mention of late night supposed to "
769 "remind us that we shouldn't trust that code?"
770 msgstr ""
771
772 #. type: Content of: <chapter><section><section><screen>
773 #: best-pkging-practices.dbk:532
774 #, no-wrap
775 msgid "  * Fix vsync FU w/ ancient CRTs.\n"
776 msgstr ""
777
778 #. type: Content of: <chapter><section><section><para>
779 #: best-pkging-practices.dbk:535
780 msgid ""
781 "Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
782 "curse word!) was actually about, or how it was fixed."
783 msgstr ""
784
785 #. type: Content of: <chapter><section><section><screen>
786 #: best-pkging-practices.dbk:539
787 #, no-wrap
788 msgid "  * This is not a bug, closes: #nnnnnn.\n"
789 msgstr ""
790
791 #. type: Content of: <chapter><section><section><para>
792 #: best-pkging-practices.dbk:542
793 msgid ""
794 "First of all, there's absolutely no need to upload the package to convey "
795 "this information; instead, use the bug tracking system.  Secondly, there's "
796 "no explanation as to why the report is not a bug."
797 msgstr ""
798
799 #. type: Content of: <chapter><section><section><screen>
800 #: best-pkging-practices.dbk:547
801 #, no-wrap
802 msgid "  * Has been fixed for ages, but I forgot to close; closes: #54321.\n"
803 msgstr ""
804
805 #. type: Content of: <chapter><section><section><para>
806 #: best-pkging-practices.dbk:550
807 msgid ""
808 "If for some reason you didn't mention the bug number in a previous changelog "
809 "entry, there's no problem, just close the bug normally in the BTS.  There's "
810 "no need to touch the changelog file, presuming the description of the fix is "
811 "already in (this applies to the fixes by the upstream authors/maintainers as "
812 "well, you don't have to track bugs that they fixed ages ago in your "
813 "changelog)."
814 msgstr ""
815
816 #. type: Content of: <chapter><section><section><screen>
817 #: best-pkging-practices.dbk:557
818 #, no-wrap
819 msgid "  * Closes: #12345, #12346, #15432\n"
820 msgstr ""
821
822 #. type: Content of: <chapter><section><section><para>
823 #: best-pkging-practices.dbk:560
824 msgid ""
825 "Where's the description? If you can't think of a descriptive message, start "
826 "by inserting the title of each different bug."
827 msgstr ""
828
829 #. type: Content of: <chapter><section><section><title>
830 #: best-pkging-practices.dbk:566
831 msgid "Supplementing changelogs with <filename>NEWS.Debian</filename> files"
832 msgstr ""
833
834 #. type: Content of: <chapter><section><section><para>
835 #: best-pkging-practices.dbk:568
836 msgid ""
837 "Important news about changes in a package can also be put in "
838 "<filename>NEWS.Debian</filename> files.  The news will be displayed by tools "
839 "like <systemitem role=\"package\">apt-listchanges</systemitem>, before all "
840 "the rest of the changelogs.  This is the preferred means to let the user "
841 "know about significant changes in a package.  It is better than using "
842 "<systemitem role=\"package\">debconf</systemitem> notes since it is less "
843 "annoying and the user can go back and refer to the "
844 "<filename>NEWS.Debian</filename> file after the install.  And it's better "
845 "than listing major changes in <filename>README.Debian</filename>, since the "
846 "user can easily miss such notes."
847 msgstr ""
848
849 #. type: Content of: <chapter><section><section><para>
850 #: best-pkging-practices.dbk:579
851 msgid ""
852 "The file format is the same as a debian changelog file, but leave off the "
853 "asterisks and describe each news item with a full paragraph when necessary "
854 "rather than the more concise summaries that would go in a changelog.  It's a "
855 "good idea to run your file through <literal>dpkg-parsechangelog</literal> to "
856 "check its formatting as it will not be automatically checked during build as "
857 "the changelog is.  Here is an example of a real "
858 "<filename>NEWS.Debian</filename> file:"
859 msgstr ""
860
861 #. type: Content of: <chapter><section><section><screen>
862 #: best-pkging-practices.dbk:588
863 #, no-wrap
864 msgid ""
865 "cron (3.0pl1-74) unstable; urgency=low\n"
866 "\n"
867 "    The checksecurity script is no longer included with the cron package:\n"
868 "    it now has its own package, checksecurity. If you liked the\n"
869 "    functionality provided with that script, please install the new\n"
870 "    package.\n"
871 "\n"
872 " -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 "
873 "-0500\n"
874 msgstr ""
875
876 #. type: Content of: <chapter><section><section><para>
877 #: best-pkging-practices.dbk:598
878 msgid ""
879 "The <filename>NEWS.Debian</filename> file is installed as "
880 "<filename>/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>.  "
881 "It is compressed, and always has that name even in Debian native packages.  "
882 "If you use <literal>debhelper</literal>, "
883 "<literal>dh_installchangelogs</literal> will install "
884 "<filename>debian/NEWS</filename> files for you."
885 msgstr ""
886
887 #. type: Content of: <chapter><section><section><para>
888 #: best-pkging-practices.dbk:605
889 msgid ""
890 "Unlike changelog files, you need not update <filename>NEWS.Debian</filename> "
891 "files with every release.  Only update them if you have something "
892 "particularly newsworthy that user should know about.  If you have no news at "
893 "all, there's no need to ship a <filename>NEWS.Debian</filename> file in your "
894 "package.  No news is good news!"
895 msgstr ""
896
897 #. type: Content of: <chapter><section><title>
898 #: best-pkging-practices.dbk:627
899 msgid "Best practices for maintainer scripts"
900 msgstr ""
901
902 #. type: Content of: <chapter><section><para>
903 #: best-pkging-practices.dbk:629
904 msgid ""
905 "Maintainer scripts include the files <filename>debian/postinst</filename>, "
906 "<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
907 "<filename>debian/postrm</filename>.  These scripts take care of any package "
908 "installation or deinstallation setup which isn't handled merely by the "
909 "creation or removal of files and directories.  The following instructions "
910 "supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
911 msgstr ""
912
913 #. type: Content of: <chapter><section><para>
914 #: best-pkging-practices.dbk:637
915 msgid ""
916 "Maintainer scripts must be idempotent.  That means that you need to make "
917 "sure nothing bad will happen if the script is called twice where it would "
918 "usually be called once."
919 msgstr ""
920
921 #. type: Content of: <chapter><section><para>
922 #: best-pkging-practices.dbk:642
923 msgid ""
924 "Standard input and output may be redirected (e.g.  into pipes) for logging "
925 "purposes, so don't rely on them being a tty."
926 msgstr ""
927
928 #. type: Content of: <chapter><section><para>
929 #: best-pkging-practices.dbk:646
930 msgid ""
931 "All prompting or interactive configuration should be kept to a minimum.  "
932 "When it is necessary, you should use the <systemitem "
933 "role=\"package\">debconf</systemitem> package for the interface.  Remember "
934 "that prompting in any case can only be in the <literal>configure</literal> "
935 "stage of the <filename>postinst</filename> script."
936 msgstr ""
937
938 #. type: Content of: <chapter><section><para>
939 #: best-pkging-practices.dbk:653
940 msgid ""
941 "Keep the maintainer scripts as simple as possible.  We suggest you use pure "
942 "POSIX shell scripts.  Remember, if you do need any bash features, the "
943 "maintainer script must have a bash shebang line.  POSIX shell or Bash are "
944 "preferred to Perl, since they enable <systemitem "
945 "role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
946 msgstr ""
947
948 #. type: Content of: <chapter><section><para>
949 #: best-pkging-practices.dbk:660
950 msgid ""
951 "If you change your maintainer scripts, be sure to test package removal, "
952 "double installation, and purging.  Be sure that a purged package is "
953 "completely gone, that is, it must remove any files created, directly or "
954 "indirectly, in any maintainer script."
955 msgstr ""
956
957 #. type: Content of: <chapter><section><para>
958 #: best-pkging-practices.dbk:666
959 msgid ""
960 "If you need to check for the existence of a command, you should use "
961 "something like"
962 msgstr ""
963
964 #. type: Content of: <chapter><section><programlisting>
965 #: best-pkging-practices.dbk:669
966 #, no-wrap
967 msgid "if [ -x /usr/sbin/install-docs ]; then ..."
968 msgstr ""
969
970 #. type: Content of: <chapter><section><para>
971 #: best-pkging-practices.dbk:671
972 msgid ""
973 "If you don't wish to hard-code the path of a command in your maintainer "
974 "script, the following POSIX-compliant shell function may help:"
975 msgstr ""
976
977 #. type: Content of: <chapter><section><para>
978 #: best-pkging-practices.dbk:676
979 msgid ""
980 "You can use this function to search <varname>$PATH</varname> for a command "
981 "name, passed as an argument.  It returns true (zero) if the command was "
982 "found, and false if not.  This is really the most portable way, since "
983 "<literal>command -v</literal>, <command>type</command>, and "
984 "<command>which</command> are not POSIX."
985 msgstr ""
986
987 #. type: Content of: <chapter><section><para>
988 #: best-pkging-practices.dbk:683
989 msgid ""
990 "While <command>which</command> is an acceptable alternative, since it is "
991 "from the required <systemitem role=\"package\">debianutils</systemitem> "
992 "package, it's not on the root partition.  That is, it's in "
993 "<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
994 "can't use it in scripts which are run before the <filename>/usr</filename> "
995 "partition is mounted.  Most scripts won't have this problem, though."
996 msgstr ""
997
998 #. type: Content of: <chapter><section><title>
999 #: best-pkging-practices.dbk:693
1000 msgid ""
1001 "Configuration management with <systemitem "
1002 "role=\"package\">debconf</systemitem>"
1003 msgstr ""
1004
1005 #. type: Content of: <chapter><section><para>
1006 #: best-pkging-practices.dbk:695
1007 msgid ""
1008 "<systemitem role=\"package\">Debconf</systemitem> is a configuration "
1009 "management system which can be used by all the various packaging scripts "
1010 "(<filename>postinst</filename> mainly) to request feedback from the user "
1011 "concerning how to configure the package.  Direct user interactions must now "
1012 "be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
1013 "interaction.  This will enable non-interactive installations in the future."
1014 msgstr ""
1015
1016 #. type: Content of: <chapter><section><para>
1017 #: best-pkging-practices.dbk:703
1018 msgid ""
1019 "Debconf is a great tool but it is often poorly used.  Many common mistakes "
1020 "are listed in the <citerefentry> "
1021 "<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
1022 "</citerefentry> man page.  It is something that you must read if you decide "
1023 "to use debconf.  Also, we document some best practices here."
1024 msgstr ""
1025
1026 #. type: Content of: <chapter><section><para>
1027 #: best-pkging-practices.dbk:710
1028 msgid ""
1029 "These guidelines include some writing style and typography recommendations, "
1030 "general considerations about debconf usage as well as more specific "
1031 "recommendations for some parts of the distribution (the installation system "
1032 "for instance)."
1033 msgstr ""
1034
1035 #. type: Content of: <chapter><section><section><title>
1036 #: best-pkging-practices.dbk:716
1037 msgid "Do not abuse debconf"
1038 msgstr ""
1039
1040 #. type: Content of: <chapter><section><section><para>
1041 #: best-pkging-practices.dbk:718
1042 msgid ""
1043 "Since debconf appeared in Debian, it has been widely abused and several "
1044 "criticisms received by the Debian distribution come from debconf abuse with "
1045 "the need of answering a wide bunch of questions before getting any little "
1046 "thing installed."
1047 msgstr ""
1048
1049 #. type: Content of: <chapter><section><section><para>
1050 #: best-pkging-practices.dbk:724
1051 msgid ""
1052 "Keep usage notes to what they belong: the <filename>NEWS.Debian</filename>, "
1053 "or <filename>README.Debian</filename> file.  Only use notes for important "
1054 "notes which may directly affect the package usability.  Remember that notes "
1055 "will always block the install until confirmed or bother the user by email."
1056 msgstr ""
1057
1058 #. type: Content of: <chapter><section><section><para>
1059 #: best-pkging-practices.dbk:730
1060 msgid ""
1061 "Carefully choose the questions priorities in maintainer scripts.  See "
1062 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1063 "<manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most "
1064 "questions should use medium and low priorities."
1065 msgstr ""
1066
1067 #. type: Content of: <chapter><section><section><title>
1068 #: best-pkging-practices.dbk:738
1069 msgid "General recommendations for authors and translators"
1070 msgstr ""
1071
1072 #. type: Content of: <chapter><section><section><section><title>
1073 #: best-pkging-practices.dbk:740
1074 msgid "Write correct English"
1075 msgstr ""
1076
1077 #. type: Content of: <chapter><section><section><section><para>
1078 #: best-pkging-practices.dbk:742
1079 msgid ""
1080 "Most Debian package maintainers are not native English speakers.  So, "
1081 "writing properly phrased templates may not be easy for them."
1082 msgstr ""
1083
1084 #. type: Content of: <chapter><section><section><section><para>
1085 #: best-pkging-practices.dbk:746
1086 msgid ""
1087 "Please use (and abuse) &email-debian-l10n-english; mailing list.  Have your "
1088 "templates proofread."
1089 msgstr ""
1090
1091 #. type: Content of: <chapter><section><section><section><para>
1092 #: best-pkging-practices.dbk:750
1093 msgid ""
1094 "Badly written templates give a poor image of your package, of your "
1095 "work... or even of Debian itself."
1096 msgstr ""
1097
1098 #. type: Content of: <chapter><section><section><section><para>
1099 #: best-pkging-practices.dbk:754
1100 msgid ""
1101 "Avoid technical jargon as much as possible.  If some terms sound common to "
1102 "you, they may be impossible to understand for others.  If you cannot avoid "
1103 "them, try to explain them (use the extended description).  When doing so, "
1104 "try to balance between verbosity and simplicity."
1105 msgstr ""
1106
1107 #. type: Content of: <chapter><section><section><section><title>
1108 #: best-pkging-practices.dbk:762
1109 msgid "Be kind to translators"
1110 msgstr ""
1111
1112 #. type: Content of: <chapter><section><section><section><para>
1113 #: best-pkging-practices.dbk:764
1114 msgid ""
1115 "Debconf templates may be translated.  Debconf, along with its sister package "
1116 "<command>po-debconf</command> offers a simple framework for getting "
1117 "templates translated by translation teams or even individuals."
1118 msgstr ""
1119
1120 #. type: Content of: <chapter><section><section><section><para>
1121 #: best-pkging-practices.dbk:769
1122 msgid ""
1123 "Please use gettext-based templates.  Install <systemitem "
1124 "role=\"package\">po-debconf</systemitem> on your development system and read "
1125 "its documentation (<command>man po-debconf</command> is a good start)."
1126 msgstr ""
1127
1128 #. type: Content of: <chapter><section><section><section><para>
1129 #: best-pkging-practices.dbk:774
1130 msgid ""
1131 "Avoid changing templates too often.  Changing templates text induces more "
1132 "work to translators which will get their translation fuzzied.  A fuzzy "
1133 "translation is a string for which the original changed since it was "
1134 "translated, therefore requiring some update by a translator to be usable.  "
1135 "When changes are small enough, the original translation is kept in PO files "
1136 "but marked as <literal>fuzzy</literal>."
1137 msgstr ""
1138
1139 #. type: Content of: <chapter><section><section><section><para>
1140 #: best-pkging-practices.dbk:782
1141 msgid ""
1142 "If you plan to do changes to your original templates, please use the "
1143 "notification system provided with the <systemitem "
1144 "role=\"package\">po-debconf</systemitem> package, namely the "
1145 "<command>podebconf-report-po</command>, to contact translators.  Most active "
1146 "translators are very responsive and getting their work included along with "
1147 "your modified templates will save you additional uploads.  If you use "
1148 "gettext-based templates, the translator's name and e-mail addresses are "
1149 "mentioned in the PO files headers and will be used by "
1150 "<command>podebconf-report-po</command>."
1151 msgstr ""
1152
1153 #. type: Content of: <chapter><section><section><section><para>
1154 #: best-pkging-practices.dbk:794
1155 msgid "A recommended use of that utility is:"
1156 msgstr ""
1157
1158 #. type: Content of: <chapter><section><section><section><programlisting>
1159 #: best-pkging-practices.dbk:796
1160 #, no-wrap
1161 msgid ""
1162 "cd debian/po &amp;&amp; podebconf-report-po --call --languageteam "
1163 "--withtranslators --deadline=\"+10 days\""
1164 msgstr ""
1165
1166 #. type: Content of: <chapter><section><section><section><para>
1167 #: best-pkging-practices.dbk:798
1168 msgid ""
1169 "This command will first synchronize the PO and POT files in "
1170 "<filename>debian/po</filename> with the templates files listed in "
1171 "<filename>debian/po/POTFILES.in</filename>.  Then, it will send a call for "
1172 "new translations, in the &email-debian-i18n; mailing list. Finally, it will "
1173 "also send a call for translation updates to the language team (mentioned in "
1174 "the <literal>Language-Team</literal> field of each PO file)  as well as the "
1175 "last translator (mentioned in <literal>Last-translator</literal>)."
1176 msgstr ""
1177
1178 #. type: Content of: <chapter><section><section><section><para>
1179 #: best-pkging-practices.dbk:807
1180 msgid ""
1181 "Giving a deadline to translators is always appreciated, so that they can "
1182 "organize their work. Please remember that some translation teams have a "
1183 "formalized translate/review process and a delay lower than 10 days is "
1184 "considered as unreasonable. A shorter delay puts too much pressure on "
1185 "translation teams and should be kept for very minor changes."
1186 msgstr ""
1187
1188 #. type: Content of: <chapter><section><section><section><para>
1189 #: best-pkging-practices.dbk:814
1190 msgid ""
1191 "If in doubt, you may also contact the translation team for a given language "
1192 "(debian-l10n-xxxxx@&lists-host;), or the &email-debian-i18n; mailing list."
1193 msgstr ""
1194
1195 #. type: Content of: <chapter><section><section><section><title>
1196 #: best-pkging-practices.dbk:821
1197 msgid "Unfuzzy complete translations when correcting typos and spelling"
1198 msgstr ""
1199
1200 #. type: Content of: <chapter><section><section><section><para>
1201 #: best-pkging-practices.dbk:823
1202 msgid ""
1203 "When the text of a debconf template is corrected and you are <emphasis "
1204 "role=\"strong\">sure</emphasis> that the change does <emphasis "
1205 "role=\"strong\">not</emphasis> affect translations, please be kind to "
1206 "translators and <emphasis>unfuzzy</emphasis> their translations."
1207 msgstr ""
1208
1209 #. type: Content of: <chapter><section><section><section><para>
1210 #: best-pkging-practices.dbk:829
1211 msgid ""
1212 "If you don't do so, the whole template will not be translated as long as a "
1213 "translator will send you an update."
1214 msgstr ""
1215
1216 #. type: Content of: <chapter><section><section><section><para>
1217 #: best-pkging-practices.dbk:833
1218 msgid ""
1219 "To <emphasis>unfuzzy</emphasis> translations, you can use "
1220 "<command>msguntypot</command> (part of the <systemitem "
1221 "role=\"package\">po4a</systemitem> package)."
1222 msgstr ""
1223
1224 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1225 #: best-pkging-practices.dbk:840
1226 msgid "Regenerate the POT and PO files."
1227 msgstr ""
1228
1229 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1230 #: best-pkging-practices.dbk:842 best-pkging-practices.dbk:865
1231 #, no-wrap
1232 msgid "debconf-updatepo"
1233 msgstr ""
1234
1235 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1236 #: best-pkging-practices.dbk:846
1237 msgid "Make a copy of the POT file."
1238 msgstr ""
1239
1240 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1241 #: best-pkging-practices.dbk:848
1242 #, no-wrap
1243 msgid "cp templates.pot templates.pot.orig"
1244 msgstr ""
1245
1246 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1247 #: best-pkging-practices.dbk:852
1248 msgid "Make a copy of all the PO files."
1249 msgstr ""
1250
1251 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1252 #: best-pkging-practices.dbk:854
1253 #, no-wrap
1254 msgid "mkdir po_fridge; cp *.po po_fridge"
1255 msgstr ""
1256
1257 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1258 #: best-pkging-practices.dbk:858
1259 msgid "Change the debconf template files to fix the typos."
1260 msgstr ""
1261
1262 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1263 #: best-pkging-practices.dbk:863
1264 msgid "Regenerate the POT and PO files (again)."
1265 msgstr ""
1266
1267 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1268 #: best-pkging-practices.dbk:867
1269 msgid ""
1270 "At this point, the typo fix fuzzied all the translations, and this "
1271 "unfortunate change is the only one between the PO files of your main "
1272 "directory and the one from the fridge. Here is how to solve this."
1273 msgstr ""
1274
1275 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1276 #: best-pkging-practices.dbk:874
1277 msgid "Discard fuzzy translation, restore the ones from the fridge."
1278 msgstr ""
1279
1280 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1281 #: best-pkging-practices.dbk:876
1282 #, no-wrap
1283 msgid "cp po_fridge/*.po ."
1284 msgstr ""
1285
1286 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1287 #: best-pkging-practices.dbk:880
1288 msgid ""
1289 "Manually merge the PO files with the new POT file, but taking the useless "
1290 "fuzzy into account."
1291 msgstr ""
1292
1293 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1294 #: best-pkging-practices.dbk:882
1295 #, no-wrap
1296 msgid "msguntypot -o templates.pot.orig -n templates.pot *.po"
1297 msgstr ""
1298
1299 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1300 #: best-pkging-practices.dbk:886
1301 msgid "Clean up."
1302 msgstr ""
1303
1304 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1305 #: best-pkging-practices.dbk:888
1306 #, no-wrap
1307 msgid "rm -rf templates.pot.orig po_fridge"
1308 msgstr ""
1309
1310 #. type: Content of: <chapter><section><section><section><title>
1311 #: best-pkging-practices.dbk:894
1312 msgid "Do not make assumptions about interfaces"
1313 msgstr ""
1314
1315 #. type: Content of: <chapter><section><section><section><para>
1316 #: best-pkging-practices.dbk:896
1317 msgid ""
1318 "Templates text should not make reference to widgets belonging to some "
1319 "debconf interfaces.  Sentences like <emphasis>If you answer "
1320 "Yes...</emphasis> have no meaning for users of graphical interfaces which "
1321 "use checkboxes for boolean questions."
1322 msgstr ""
1323
1324 #. type: Content of: <chapter><section><section><section><para>
1325 #: best-pkging-practices.dbk:901
1326 msgid ""
1327 "String templates should also avoid mentioning the default values in their "
1328 "description.  First, because this is redundant with the values seen by the "
1329 "users.  Also, because these default values may be different from the "
1330 "maintainer choices (for instance, when the debconf database was preseeded)."
1331 msgstr ""
1332
1333 #. type: Content of: <chapter><section><section><section><para>
1334 #: best-pkging-practices.dbk:907
1335 msgid ""
1336 "More generally speaking, try to avoid referring to user actions.  Just give "
1337 "facts."
1338 msgstr ""
1339
1340 #. type: Content of: <chapter><section><section><section><title>
1341 #: best-pkging-practices.dbk:913
1342 msgid "Do not use first person"
1343 msgstr ""
1344
1345 #. type: Content of: <chapter><section><section><section><para>
1346 #: best-pkging-practices.dbk:915
1347 msgid ""
1348 "You should avoid the use of first person (<emphasis>I will do "
1349 "this...</emphasis> or <emphasis>We recommend...</emphasis>).  The computer "
1350 "is not a person and the Debconf templates do not speak for the Debian "
1351 "developers.  You should use neutral construction.  Those of you who already "
1352 "wrote scientific publications, just write your templates like you would "
1353 "write a scientific paper.  However, try using active voice if still "
1354 "possible, like <emphasis>Enable this if ...</emphasis> instead of "
1355 "<emphasis>This can be enabled if...</emphasis>."
1356 msgstr ""
1357
1358 #. type: Content of: <chapter><section><section><section><title>
1359 #: best-pkging-practices.dbk:925
1360 msgid "Be gender neutral"
1361 msgstr ""
1362
1363 #. type: Content of: <chapter><section><section><section><para>
1364 #: best-pkging-practices.dbk:927
1365 msgid ""
1366 "The world is made of men and women.  Please use gender-neutral constructions "
1367 "in your writing."
1368 msgstr ""
1369
1370 #. type: Content of: <chapter><section><section><title>
1371 #: best-pkging-practices.dbk:935
1372 msgid "Templates fields definition"
1373 msgstr ""
1374
1375 #. type: Content of: <chapter><section><section><para>
1376 #: best-pkging-practices.dbk:937
1377 msgid ""
1378 "This part gives some information which is mostly taken from the "
1379 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1380 "<manvolnum>7</manvolnum> </citerefentry> manual page."
1381 msgstr ""
1382
1383 #. type: Content of: <chapter><section><section><section><title>
1384 #: best-pkging-practices.dbk:942
1385 msgid "Type"
1386 msgstr ""
1387
1388 #. type: Content of: <chapter><section><section><section><section><title>
1389 #: best-pkging-practices.dbk:944
1390 msgid "string"
1391 msgstr ""
1392
1393 #. type: Content of: <chapter><section><section><section><section><para>
1394 #: best-pkging-practices.dbk:946
1395 msgid "Results in a free-form input field that the user can type any string into."
1396 msgstr ""
1397
1398 #. type: Content of: <chapter><section><section><section><section><title>
1399 #: best-pkging-practices.dbk:951
1400 msgid "password"
1401 msgstr ""
1402
1403 #. type: Content of: <chapter><section><section><section><section><para>
1404 #: best-pkging-practices.dbk:953
1405 msgid ""
1406 "Prompts the user for a password.  Use this with caution; be aware that the "
1407 "password the user enters will be written to debconf's database.  You should "
1408 "probably clean that value out of the database as soon as is possible."
1409 msgstr ""
1410
1411 #. type: Content of: <chapter><section><section><section><section><title>
1412 #: best-pkging-practices.dbk:960
1413 msgid "boolean"
1414 msgstr ""
1415
1416 #. type: Content of: <chapter><section><section><section><section><para>
1417 #: best-pkging-practices.dbk:962
1418 msgid ""
1419 "A true/false choice.  Remember: true/false, <emphasis role=\"strong\">not "
1420 "yes/no</emphasis>..."
1421 msgstr ""
1422
1423 #. type: Content of: <chapter><section><section><section><section><title>
1424 #: best-pkging-practices.dbk:968
1425 msgid "select"
1426 msgstr ""
1427
1428 #. type: Content of: <chapter><section><section><section><section><para>
1429 #: best-pkging-practices.dbk:970
1430 msgid ""
1431 "A choice between one of a number of values.  The choices must be specified "
1432 "in a field named 'Choices'.  Separate the possible values with commas and "
1433 "spaces, like this: <literal>Choices: yes, no, maybe</literal>."
1434 msgstr ""
1435
1436 #. type: Content of: <chapter><section><section><section><section><para>
1437 #: best-pkging-practices.dbk:975
1438 msgid ""
1439 "If choices are translatable strings, the 'Choices' field may be marked as "
1440 "translatable by using <literal>__Choices</literal>. The double underscore "
1441 "will split out each choice in a separate string."
1442 msgstr ""
1443
1444 #. type: Content of: <chapter><section><section><section><section><para>
1445 #: best-pkging-practices.dbk:980
1446 msgid ""
1447 "The <command>po-debconf</command> system also offers interesting "
1448 "possibilities to only mark <emphasis role=\"strong\">some</emphasis> choices "
1449 "as translatable.  Example:"
1450 msgstr ""
1451
1452 #. type: Content of: <chapter><section><section><section><section><programlisting>
1453 #: best-pkging-practices.dbk:985
1454 #, no-wrap
1455 msgid ""
1456 "Template: foo/bar\n"
1457 "Type: Select\n"
1458 "#flag:translate:3\n"
1459 "__Choices: PAL, SECAM, Other\n"
1460 "_Description: TV standard:\n"
1461 " Please choose the TV standard used in your country.\n"
1462 msgstr ""
1463
1464 #. type: Content of: <chapter><section><section><section><section><para>
1465 #: best-pkging-practices.dbk:993
1466 msgid ""
1467 "In that example, only the 'Other' string is translatable while others are "
1468 "acronyms that should not be translated. The above allows only 'Other' to be "
1469 "included in PO and POT files."
1470 msgstr ""
1471
1472 #. type: Content of: <chapter><section><section><section><section><para>
1473 #: best-pkging-practices.dbk:998
1474 msgid ""
1475 "The debconf templates flag system offers many such possibilities. The "
1476 "<citerefentry> <refentrytitle>po-debconf</refentrytitle> "
1477 "<manvolnum>7</manvolnum> </citerefentry> manual page lists all these "
1478 "possibilities."
1479 msgstr ""
1480
1481 #. type: Content of: <chapter><section><section><section><section><title>
1482 #: best-pkging-practices.dbk:1006
1483 msgid "multiselect"
1484 msgstr ""
1485
1486 #. type: Content of: <chapter><section><section><section><section><para>
1487 #: best-pkging-practices.dbk:1008
1488 msgid ""
1489 "Like the select data type, except the user can choose any number of items "
1490 "from the choices list (or chose none of them)."
1491 msgstr ""
1492
1493 #. type: Content of: <chapter><section><section><section><section><title>
1494 #: best-pkging-practices.dbk:1014
1495 msgid "note"
1496 msgstr ""
1497
1498 #. type: Content of: <chapter><section><section><section><section><para>
1499 #: best-pkging-practices.dbk:1016
1500 msgid ""
1501 "Rather than being a question per se, this datatype indicates a note that can "
1502 "be displayed to the user.  It should be used only for important notes that "
1503 "the user really should see, since debconf will go to great pains to make "
1504 "sure the user sees it; halting the install for them to press a key, and even "
1505 "mailing the note to them in some cases."
1506 msgstr ""
1507
1508 #. type: Content of: <chapter><section><section><section><section><title>
1509 #: best-pkging-practices.dbk:1025
1510 msgid "text"
1511 msgstr ""
1512
1513 #. type: Content of: <chapter><section><section><section><section><para>
1514 #: best-pkging-practices.dbk:1027
1515 msgid "This type is now considered obsolete: don't use it."
1516 msgstr ""
1517
1518 #. type: Content of: <chapter><section><section><section><section><title>
1519 #: best-pkging-practices.dbk:1032
1520 msgid "error"
1521 msgstr ""
1522
1523 #. type: Content of: <chapter><section><section><section><section><para>
1524 #: best-pkging-practices.dbk:1034
1525 msgid ""
1526 "This type is designed to handle error messages.  It is mostly similar to the "
1527 "note type.  Frontends may present it differently (for instance, the dialog "
1528 "frontend of cdebconf draws a red screen instead of the usual blue one)."
1529 msgstr ""
1530
1531 #. type: Content of: <chapter><section><section><section><section><para>
1532 #: best-pkging-practices.dbk:1039
1533 msgid ""
1534 "It is recommended to use this type for any message that needs user attention "
1535 "for a correction of any kind."
1536 msgstr ""
1537
1538 #. type: Content of: <chapter><section><section><section><title>
1539 #: best-pkging-practices.dbk:1047
1540 msgid "Description: short and extended description"
1541 msgstr ""
1542
1543 #. type: Content of: <chapter><section><section><section><para>
1544 #: best-pkging-practices.dbk:1049
1545 msgid ""
1546 "Template descriptions have two parts: short and extended.  The short "
1547 "description is in the Description: line of the template."
1548 msgstr ""
1549
1550 #. type: Content of: <chapter><section><section><section><para>
1551 #: best-pkging-practices.dbk:1053
1552 msgid ""
1553 "The short description should be kept short (50 characters or so) so that it "
1554 "may be accommodated by most debconf interfaces.  Keeping it short also helps "
1555 "translators, as usually translations tend to end up being longer than the "
1556 "original."
1557 msgstr ""
1558
1559 #. type: Content of: <chapter><section><section><section><para>
1560 #: best-pkging-practices.dbk:1059
1561 msgid ""
1562 "The short description should be able to stand on its own.  Some interfaces "
1563 "do not show the long description by default, or only if the user explicitely "
1564 "asks for it or even do not show it at all.  Avoid things like What do you "
1565 "want to do?"
1566 msgstr ""
1567
1568 #. type: Content of: <chapter><section><section><section><para>
1569 #: best-pkging-practices.dbk:1065
1570 msgid ""
1571 "The short description does not necessarily have to be a full sentence.  This "
1572 "is part of the keep it short and efficient recommendation."
1573 msgstr ""
1574
1575 #. type: Content of: <chapter><section><section><section><para>
1576 #: best-pkging-practices.dbk:1069
1577 msgid ""
1578 "The extended description should not repeat the short description word for "
1579 "word.  If you can't think up a long description, then first, think some "
1580 "more.  Post to debian-devel.  Ask for help.  Take a writing class! That "
1581 "extended description is important.  If after all that you still can't come "
1582 "up with anything, leave it blank."
1583 msgstr ""
1584
1585 #. type: Content of: <chapter><section><section><section><para>
1586 #: best-pkging-practices.dbk:1076
1587 msgid ""
1588 "The extended description should use complete sentences.  Paragraphs should "
1589 "be kept short for improved readability.  Do not mix two ideas in the same "
1590 "paragraph but rather use another paragraph."
1591 msgstr ""
1592
1593 #. type: Content of: <chapter><section><section><section><para>
1594 #: best-pkging-practices.dbk:1081
1595 msgid ""
1596 "Don't be too verbose.  User tend to ignore too long screens.  20 lines are "
1597 "by experience a border you shouldn't cross, because that means that in the "
1598 "classical dialog interface, people will need to scroll, and lot of people "
1599 "just don't do that."
1600 msgstr ""
1601
1602 #. type: Content of: <chapter><section><section><section><para>
1603 #: best-pkging-practices.dbk:1087
1604 msgid ""
1605 "The extended description should <emphasis role=\"strong\">never</emphasis> "
1606 "include a question."
1607 msgstr ""
1608
1609 #. type: Content of: <chapter><section><section><section><para>
1610 #: best-pkging-practices.dbk:1091
1611 msgid ""
1612 "For specific rules depending on templates type (string, boolean, etc.), "
1613 "please read below."
1614 msgstr ""
1615
1616 #. type: Content of: <chapter><section><section><section><title>
1617 #: best-pkging-practices.dbk:1097
1618 msgid "Choices"
1619 msgstr ""
1620
1621 #. type: Content of: <chapter><section><section><section><para>
1622 #: best-pkging-practices.dbk:1099
1623 msgid ""
1624 "This field should be used for select and multiselect types.  It contains the "
1625 "possible choices which will be presented to users.  These choices should be "
1626 "separated by commas."
1627 msgstr ""
1628
1629 #. type: Content of: <chapter><section><section><section><title>
1630 #: best-pkging-practices.dbk:1106
1631 msgid "Default"
1632 msgstr ""
1633
1634 #. type: Content of: <chapter><section><section><section><para>
1635 #: best-pkging-practices.dbk:1108
1636 msgid ""
1637 "This field is optional.  It contains the default answer for string, select "
1638 "and multiselect templates.  For multiselect templates, it may contain a "
1639 "comma-separated list of choices."
1640 msgstr ""
1641
1642 #. type: Content of: <chapter><section><section><title>
1643 #: best-pkging-practices.dbk:1117
1644 msgid "Templates fields specific style guide"
1645 msgstr ""
1646
1647 #. type: Content of: <chapter><section><section><section><title>
1648 #: best-pkging-practices.dbk:1119
1649 msgid "Type field"
1650 msgstr ""
1651
1652 #. type: Content of: <chapter><section><section><section><para>
1653 #: best-pkging-practices.dbk:1121
1654 msgid ""
1655 "No specific indication except: use the appropriate type by referring to the "
1656 "previous section."
1657 msgstr ""
1658
1659 #. type: Content of: <chapter><section><section><section><title>
1660 #: best-pkging-practices.dbk:1127
1661 msgid "Description field"
1662 msgstr ""
1663
1664 #. type: Content of: <chapter><section><section><section><para>
1665 #: best-pkging-practices.dbk:1129
1666 msgid ""
1667 "Below are specific instructions for properly writing the Description (short "
1668 "and extended) depending on the template type."
1669 msgstr ""
1670
1671 #. type: Content of: <chapter><section><section><section><section><title>
1672 #: best-pkging-practices.dbk:1133
1673 msgid "String/password templates"
1674 msgstr ""
1675
1676 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1677 #: best-pkging-practices.dbk:1137
1678 msgid ""
1679 "The short description is a prompt and <emphasis "
1680 "role=\"strong\">not</emphasis> a title.  Avoid question style prompts (IP "
1681 "Address?) in favour of opened prompts (IP address:).  The use of colons is "
1682 "recommended."
1683 msgstr ""
1684
1685 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1686 #: best-pkging-practices.dbk:1144
1687 msgid ""
1688 "The extended description is a complement to the short description.  In the "
1689 "extended part, explain what is being asked, rather than ask the same "
1690 "question again using longer words.  Use complete sentences.  Terse writing "
1691 "style is strongly discouraged."
1692 msgstr ""
1693
1694 #. type: Content of: <chapter><section><section><section><section><title>
1695 #: best-pkging-practices.dbk:1154
1696 msgid "Boolean templates"
1697 msgstr ""
1698
1699 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1700 #: best-pkging-practices.dbk:1158
1701 msgid ""
1702 "The short description should be phrased in the form of a question which "
1703 "should be kept short and should generally end with a question mark.  Terse "
1704 "writing style is permitted and even encouraged if the question is rather "
1705 "long (remember that translations are often longer than original versions)."
1706 msgstr ""
1707
1708 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1709 #: best-pkging-practices.dbk:1166
1710 msgid ""
1711 "Again, please avoid referring to specific interface widgets.  A common "
1712 "mistake for such templates is if you answer Yes-type constructions."
1713 msgstr ""
1714
1715 #. type: Content of: <chapter><section><section><section><section><title>
1716 #: best-pkging-practices.dbk:1174
1717 msgid "Select/Multiselect"
1718 msgstr ""
1719
1720 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1721 #: best-pkging-practices.dbk:1178
1722 msgid ""
1723 "The short description is a prompt and <emphasis "
1724 "role=\"strong\">not</emphasis> a title.  Do <emphasis "
1725 "role=\"strong\">not</emphasis> use useless Please choose...  constructions.  "
1726 "Users are clever enough to figure out they have to choose something...:)"
1727 msgstr ""
1728
1729 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1730 #: best-pkging-practices.dbk:1186
1731 msgid ""
1732 "The extended description will complete the short description.  It may refer "
1733 "to the available choices.  It may also mention that the user may choose more "
1734 "than one of the available choices, if the template is a multiselect one "
1735 "(although the interface often makes this clear)."
1736 msgstr ""
1737
1738 #. type: Content of: <chapter><section><section><section><section><title>
1739 #: best-pkging-practices.dbk:1196
1740 msgid "Notes"
1741 msgstr ""
1742
1743 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1744 #: best-pkging-practices.dbk:1200
1745 msgid ""
1746 "The short description should be considered to be a <emphasis "
1747 "role=\"strong\">title</emphasis>."
1748 msgstr ""
1749
1750 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1751 #: best-pkging-practices.dbk:1205
1752 msgid ""
1753 "The extended description is what will be displayed as a more detailed "
1754 "explanation of the note.  Phrases, no terse writing style."
1755 msgstr ""
1756
1757 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1758 #: best-pkging-practices.dbk:1211
1759 msgid ""
1760 "<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
1761 "most common way to abuse debconf.  As written in debconf-devel manual page: "
1762 "it's best to use them only for warning about very serious problems.  The "
1763 "<filename>NEWS.Debian</filename> or <filename>README.Debian</filename> files "
1764 "are the appropriate location for a lot of notes.  If, by reading this, you "
1765 "consider converting your Note type templates to entries in "
1766 "<filename>NEWS.Debian</filename> or <filename>README.Debian</filename>, plus "
1767 "consider keeping existing translations for the future."
1768 msgstr ""
1769
1770 #. type: Content of: <chapter><section><section><section><title>
1771 #: best-pkging-practices.dbk:1226
1772 msgid "Choices field"
1773 msgstr ""
1774
1775 #. type: Content of: <chapter><section><section><section><para>
1776 #: best-pkging-practices.dbk:1228
1777 msgid ""
1778 "If the Choices are likely to change often, please consider using the "
1779 "__Choices trick.  This will split each individual choice into a single "
1780 "string, which will considerably help translators for doing their work."
1781 msgstr ""
1782
1783 #. type: Content of: <chapter><section><section><section><title>
1784 #: best-pkging-practices.dbk:1235 best-pkging-practices.dbk:1273
1785 msgid "Default field"
1786 msgstr ""
1787
1788 #. type: Content of: <chapter><section><section><section><para>
1789 #: best-pkging-practices.dbk:1237
1790 msgid ""
1791 "If the default value, for a select template, is likely to vary depending on "
1792 "the user language (for instance, if the choice is a language choice), please "
1793 "use the _Default trick."
1794 msgstr ""
1795
1796 #. type: Content of: <chapter><section><section><section><para>
1797 #: best-pkging-practices.dbk:1242
1798 msgid ""
1799 "This special field allow translators to put the most appropriate choice "
1800 "according to their own language.  It will become the default choice when "
1801 "their language is used while your own mentioned Default Choice will be used "
1802 "when using English."
1803 msgstr ""
1804
1805 #. type: Content of: <chapter><section><section><section><para>
1806 #: best-pkging-practices.dbk:1248
1807 msgid "Example, taken from the geneweb package templates:"
1808 msgstr ""
1809
1810 #. type: Content of: <chapter><section><section><section><screen>
1811 #: best-pkging-practices.dbk:1251
1812 #, no-wrap
1813 msgid ""
1814 "Template: geneweb/lang\n"
1815 "Type: select\n"
1816 "__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech "
1817 "(cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), "
1818 "Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian "
1819 "(it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian "
1820 "(ro), Russian (ru), Spanish (es), Swedish (sv)\n"
1821 "# This is the default choice. Translators may put their own language here\n"
1822 "# instead of the default.\n"
1823 "# WARNING : you MUST use the ENGLISH NAME of your language\n"
1824 "# For instance, the french translator will need to put French (fr) here.\n"
1825 "_Default: English[ translators, please see comment in PO files]\n"
1826 "_Description: Geneweb default language:\n"
1827 msgstr ""
1828
1829 #. type: Content of: <chapter><section><section><section><para>
1830 #: best-pkging-practices.dbk:1262
1831 msgid ""
1832 "Note the use of brackets which allow internal comments in debconf fields.  "
1833 "Also note the use of comments which will show up in files the translators "
1834 "will work with."
1835 msgstr ""
1836
1837 #. type: Content of: <chapter><section><section><section><para>
1838 #: best-pkging-practices.dbk:1267
1839 msgid ""
1840 "The comments are needed as the _Default trick is a bit confusing: the "
1841 "translators may put their own choice"
1842 msgstr ""
1843
1844 #. type: Content of: <chapter><section><section><section><para>
1845 #: best-pkging-practices.dbk:1275
1846 msgid ""
1847 "Do NOT use empty default field.  If you don't want to use default values, do "
1848 "not use Default at all."
1849 msgstr ""
1850
1851 #. type: Content of: <chapter><section><section><section><para>
1852 #: best-pkging-practices.dbk:1279
1853 msgid ""
1854 "If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
1855 "see <xref linkend=\"s6.5.2.2\"/>), consider making this field translatable, "
1856 "if you think it may be translated."
1857 msgstr ""
1858
1859 #. type: Content of: <chapter><section><section><section><para>
1860 #: best-pkging-practices.dbk:1284
1861 msgid ""
1862 "If the default value may vary depending on language/country (for instance "
1863 "the default value for a language choice), consider using the special "
1864 "_Default type documented in <citerefentry> "
1865 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1866 "</citerefentry>."
1867 msgstr ""
1868
1869 #. type: Content of: <chapter><section><title>
1870 #: best-pkging-practices.dbk:1296
1871 msgid "Internationalization"
1872 msgstr ""
1873
1874 #. type: Content of: <chapter><section><para>
1875 #: best-pkging-practices.dbk:1298
1876 msgid ""
1877 "This section contains global information for developers to make translators' "
1878 "life easier.  More information for translators and developers interested in "
1879 "internationalization are available in the <ulink "
1880 "url=\"&url-i18n-l10n;\">Internationalisation and localisation in "
1881 "Debian</ulink> documentation."
1882 msgstr ""
1883
1884 #. type: Content of: <chapter><section><section><title>
1885 #: best-pkging-practices.dbk:1305
1886 msgid "Handling debconf translations"
1887 msgstr ""
1888
1889 #. type: Content of: <chapter><section><section><para>
1890 #: best-pkging-practices.dbk:1307
1891 msgid ""
1892 "Like porters, translators have a difficult task.  They work on many packages "
1893 "and must collaborate with many different maintainers.  Moreover, most of the "
1894 "time, they are not native English speakers, so you may need to be "
1895 "particularly patient with them."
1896 msgstr ""
1897
1898 #. type: Content of: <chapter><section><section><para>
1899 #: best-pkging-practices.dbk:1313
1900 msgid ""
1901 "The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
1902 "packages configuration easier for maintainers and for users.  Originally, "
1903 "translation of debconf templates was handled with "
1904 "<command>debconf-mergetemplate</command>.  However, that technique is now "
1905 "deprecated; the best way to accomplish <systemitem "
1906 "role=\"package\">debconf</systemitem> internationalization is by using the "
1907 "<systemitem role=\"package\">po-debconf</systemitem> package.  This method "
1908 "is easier both for maintainer and translators; transition scripts are "
1909 "provided."
1910 msgstr ""
1911
1912 #. type: Content of: <chapter><section><section><para>
1913 #: best-pkging-practices.dbk:1323
1914 msgid ""
1915 "Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
1916 "is stored in <filename>.po</filename> files (drawing from "
1917 "<command>gettext</command> translation techniques).  Special template files "
1918 "contain the original messages and mark which fields are translatable.  When "
1919 "you change the value of a translatable field, by calling "
1920 "<command>debconf-updatepo</command>, the translation is marked as needing "
1921 "attention from the translators.  Then, at build time, the "
1922 "<command>dh_installdebconf</command> program takes care of all the needed "
1923 "magic to add the template along with the up-to-date translations into the "
1924 "binary packages.  Refer to the <citerefentry> "
1925 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1926 "</citerefentry> manual page for details."
1927 msgstr ""
1928
1929 #. type: Content of: <chapter><section><section><title>
1930 #: best-pkging-practices.dbk:1339
1931 msgid "Internationalized documentation"
1932 msgstr ""
1933
1934 #. type: Content of: <chapter><section><section><para>
1935 #: best-pkging-practices.dbk:1341
1936 msgid ""
1937 "Internationalizing documentation is crucial for users, but a lot of labor.  "
1938 "There's no way to eliminate all that work, but you can make things easier "
1939 "for translators."
1940 msgstr ""
1941
1942 #. type: Content of: <chapter><section><section><para>
1943 #: best-pkging-practices.dbk:1346
1944 msgid ""
1945 "If you maintain documentation of any size, it is easier for translators if "
1946 "they have access to a source control system.  That lets translators see the "
1947 "differences between two versions of the documentation, so, for instance, "
1948 "they can see what needs to be retranslated.  It is recommended that the "
1949 "translated documentation maintain a note about what source control revision "
1950 "the translation is based on.  An interesting system is provided by <ulink "
1951 "url=\"&url-i18n-doc-check;\">doc-check</ulink> in the <systemitem "
1952 "role=\"package\">debian-installer</systemitem> package, which shows an "
1953 "overview of the translation status for any given language, using structured "
1954 "comments for the current revision of the file to be translated and, for a "
1955 "translated file, the revision of the original file the translation is based "
1956 "on.  You might wish to adapt and provide that in your VCS area."
1957 msgstr ""
1958
1959 #. type: Content of: <chapter><section><section><para>
1960 #: best-pkging-practices.dbk:1360
1961 msgid ""
1962 "If you maintain XML or SGML documentation, we suggest that you isolate any "
1963 "language-independent information and define those as entities in a separate "
1964 "file which is included by all the different translations.  This makes it "
1965 "much easier, for instance, to keep URLs up to date across multiple files."
1966 msgstr ""
1967
1968 #. type: Content of: <chapter><section><section><para>
1969 #: best-pkging-practices.dbk:1366
1970 msgid ""
1971 "Some tools (e.g. <systemitem role=\"package\">po4a</systemitem>, <systemitem "
1972 "role=\"package\">poxml</systemitem>, or the <systemitem "
1973 "role=\"package\">translate-toolkit</systemitem>) are specialized in "
1974 "extracting the translatable material from different formats.  They produce "
1975 "PO files, a format quite common to translators, which permits to see what "
1976 "needs to be retranslated when the translated document is updated."
1977 msgstr ""
1978
1979 #. type: Content of: <chapter><section><title>
1980 #: best-pkging-practices.dbk:1378
1981 msgid "Common packaging situations"
1982 msgstr ""
1983
1984 #. type: Content of: <chapter><section><section><title>
1985 #: best-pkging-practices.dbk:1389
1986 msgid "Packages using <command>autoconf</command>/<command>automake</command>"
1987 msgstr ""
1988
1989 #. type: Content of: <chapter><section><section><para>
1990 #: best-pkging-practices.dbk:1391
1991 msgid ""
1992 "Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
1993 "<filename>config.guess</filename> files up to date is critical for porters, "
1994 "especially on more volatile architectures.  Some very good packaging "
1995 "practices for any package using <command>autoconf</command> and/or "
1996 "<command>automake</command> have been synthesized in &file-bpp-autotools; "
1997 "from the <systemitem role=\"package\">autotools-dev</systemitem> package.  "
1998 "You're strongly encouraged to read this file and to follow the given "
1999 "recommendations."
2000 msgstr ""
2001
2002 #. type: Content of: <chapter><section><section><title>
2003 #: best-pkging-practices.dbk:1403
2004 msgid "Libraries"
2005 msgstr ""
2006
2007 #. type: Content of: <chapter><section><section><para>
2008 #: best-pkging-practices.dbk:1405
2009 msgid ""
2010 "Libraries are always difficult to package for various reasons.  The policy "
2011 "imposes many constraints to ease their maintenance and to make sure upgrades "
2012 "are as simple as possible when a new upstream version comes out.  Breakage "
2013 "in a library can result in dozens of dependent packages breaking."
2014 msgstr ""
2015
2016 #. type: Content of: <chapter><section><section><para>
2017 #: best-pkging-practices.dbk:1411
2018 msgid ""
2019 "Good practices for library packaging have been grouped in <ulink "
2020 "url=\"&url-libpkg-guide;\">the library packaging guide</ulink>."
2021 msgstr ""
2022
2023 #. type: Content of: <chapter><section><title>
2024 #: best-pkging-practices.dbk:1418 resources.dbk:193
2025 msgid "Documentation"
2026 msgstr ""
2027
2028 #. type: Content of: <chapter><section><section><para>
2029 #: best-pkging-practices.dbk:1420
2030 msgid ""
2031 "Be sure to follow the <ulink url=\"&url-debian-policy;ch-docs.html\">Policy "
2032 "on documentation</ulink>."
2033 msgstr ""
2034
2035 #. type: Content of: <chapter><section><section><para>
2036 #: best-pkging-practices.dbk:1425
2037 msgid ""
2038 "If your package contains documentation built from XML or SGML, we recommend "
2039 "you not ship the XML or SGML source in the binary package(s).  If users want "
2040 "the source of the documentation, they should retrieve the source package."
2041 msgstr ""
2042
2043 #. type: Content of: <chapter><section><section><para>
2044 #: best-pkging-practices.dbk:1430
2045 msgid ""
2046 "Policy specifies that documentation should be shipped in HTML format.  We "
2047 "also recommend shipping documentation in PDF and plain text format if "
2048 "convenient and if output of reasonable quality is possible.  However, it is "
2049 "generally not appropriate to ship plain text versions of documentation whose "
2050 "source format is HTML."
2051 msgstr ""
2052
2053 #. type: Content of: <chapter><section><section><para>
2054 #: best-pkging-practices.dbk:1437
2055 msgid ""
2056 "Major shipped manuals should register themselves with <systemitem "
2057 "role=\"package\">doc-base</systemitem> on installation.  See the <systemitem "
2058 "role=\"package\">doc-base</systemitem> package documentation for more "
2059 "information."
2060 msgstr ""
2061
2062 #. type: Content of: <chapter><section><section><para>
2063 #: best-pkging-practices.dbk:1443
2064 msgid ""
2065 "Debian policy (section 12.1) directs that manual pages should accompany "
2066 "every program, utility, and function, and suggests them for other objects "
2067 "like configuration files. If the work you are packaging does not have such "
2068 "manual pages, consider writing them for inclusion in your package, and "
2069 "submitting them upstream."
2070 msgstr ""
2071
2072 #. type: Content of: <chapter><section><section><para>
2073 #: best-pkging-practices.dbk:1450
2074 msgid ""
2075 "The manpages do not need to be written directly in the troff format.  "
2076 "Popular source formats are Docbook, POD and reST, which can be converted "
2077 "using <command>xsltproc</command>, <command>pod2man</command> and "
2078 "<command>rst2man</command> respectively. To a lesser extent, the "
2079 "<command>help2man</command> program can also be used to write a stub."
2080 msgstr ""
2081
2082 #. type: Content of: <chapter><section><section><title>
2083 #: best-pkging-practices.dbk:1459
2084 msgid "Specific types of packages"
2085 msgstr ""
2086
2087 #. type: Content of: <chapter><section><section><para>
2088 #: best-pkging-practices.dbk:1461
2089 msgid ""
2090 "Several specific types of packages have special sub-policies and "
2091 "corresponding packaging rules and practices:"
2092 msgstr ""
2093
2094 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2095 #: best-pkging-practices.dbk:1467
2096 msgid ""
2097 "Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
2098 "policy</ulink>, some examples of packages following that policy are "
2099 "<systemitem role=\"package\">libdbd-pg-perl</systemitem> (binary perl "
2100 "module) or <systemitem role=\"package\">libmldbm-perl</systemitem> (arch "
2101 "independent perl module)."
2102 msgstr ""
2103
2104 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2105 #: best-pkging-practices.dbk:1476
2106 msgid ""
2107 "Python related packages have their python policy; see &file-python-policy; "
2108 "in the <systemitem role=\"package\">python</systemitem> package."
2109 msgstr ""
2110
2111 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2112 #: best-pkging-practices.dbk:1483
2113 msgid ""
2114 "Emacs related packages have the <ulink url=\"&url-emacs-policy;\">emacs "
2115 "policy</ulink>."
2116 msgstr ""
2117
2118 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2119 #: best-pkging-practices.dbk:1490
2120 msgid ""
2121 "Java related packages have their <ulink url=\"&url-java-policy;\">java "
2122 "policy</ulink>."
2123 msgstr ""
2124
2125 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2126 #: best-pkging-practices.dbk:1497
2127 msgid ""
2128 "Ocaml related packages have their own policy, found in &file-ocaml-policy; "
2129 "from the <systemitem role=\"package\">ocaml</systemitem> package.  A good "
2130 "example is the <systemitem role=\"package\">camlzip</systemitem> source "
2131 "package."
2132 msgstr ""
2133
2134 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2135 #: best-pkging-practices.dbk:1505
2136 msgid ""
2137 "Packages providing XML or SGML DTDs should conform to the recommendations "
2138 "found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
2139 "package."
2140 msgstr ""
2141
2142 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2143 #: best-pkging-practices.dbk:1511
2144 msgid ""
2145 "Lisp packages should register themselves with <systemitem "
2146 "role=\"package\">common-lisp-controller</systemitem>, about which see "
2147 "&file-lisp-controller;."
2148 msgstr ""
2149
2150 #. type: Content of: <chapter><section><section><title>
2151 #: best-pkging-practices.dbk:1541
2152 msgid "Architecture-independent data"
2153 msgstr ""
2154
2155 #. type: Content of: <chapter><section><section><para>
2156 #: best-pkging-practices.dbk:1543
2157 msgid ""
2158 "It is not uncommon to have a large amount of architecture-independent data "
2159 "packaged with a program.  For example, audio files, a collection of icons, "
2160 "wallpaper patterns, or other graphic files.  If the size of this data is "
2161 "negligible compared to the size of the rest of the package, it's probably "
2162 "best to keep it all in a single package."
2163 msgstr ""
2164
2165 #. type: Content of: <chapter><section><section><para>
2166 #: best-pkging-practices.dbk:1550
2167 msgid ""
2168 "However, if the size of the data is considerable, consider splitting it out "
2169 "into a separate, architecture-independent package "
2170 "(<filename>_all.deb</filename>).  By doing this, you avoid needless "
2171 "duplication of the same data into eleven or more .debs, one per each "
2172 "architecture.  While this adds some extra overhead into the "
2173 "<filename>Packages</filename> files, it saves a lot of disk space on Debian "
2174 "mirrors.  Separating out architecture-independent data also reduces "
2175 "processing time of <command>lintian</command> (see <xref "
2176 "linkend=\"tools-lint\"/>) when run over the entire Debian archive."
2177 msgstr ""
2178
2179 #. type: Content of: <chapter><section><section><title>
2180 #: best-pkging-practices.dbk:1562
2181 msgid "Needing a certain locale during build"
2182 msgstr ""
2183
2184 #. type: Content of: <chapter><section><section><para>
2185 #: best-pkging-practices.dbk:1564
2186 msgid ""
2187 "If you need a certain locale during build, you can create a temporary file "
2188 "via this trick:"
2189 msgstr ""
2190
2191 #. type: Content of: <chapter><section><section><para>
2192 #: best-pkging-practices.dbk:1568
2193 msgid ""
2194 "If you set <varname>LOCPATH</varname> to the equivalent of "
2195 "<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
2196 "name of the locale you generate, you should get what you want without being "
2197 "root.  Something like this:"
2198 msgstr ""
2199
2200 #. type: Content of: <chapter><section><section><screen>
2201 #: best-pkging-practices.dbk:1573
2202 #, no-wrap
2203 msgid ""
2204 "LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
2205 "LOCALE_NAME=en_IN\n"
2206 "LOCALE_CHARSET=UTF-8\n"
2207 "\n"
2208 "mkdir -p $LOCALE_PATH\n"
2209 "localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
2210 "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
2211 "\n"
2212 "# Using the locale\n"
2213 "LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date\n"
2214 msgstr ""
2215
2216 #. type: Content of: <chapter><section><section><title>
2217 #: best-pkging-practices.dbk:1586
2218 msgid "Make transition packages deborphan compliant"
2219 msgstr ""
2220
2221 #. type: Content of: <chapter><section><section><para>
2222 #: best-pkging-practices.dbk:1588
2223 msgid ""
2224 "Deborphan is a program for helping users to detect which packages can safely "
2225 "be removed from the system, i.e.  the ones that have no packages depending "
2226 "on them.  The default operation is to search only within the libs and "
2227 "oldlibs sections, to hunt down unused libraries.  But when passed the right "
2228 "argument, it tries to catch other useless packages."
2229 msgstr ""
2230
2231 #. type: Content of: <chapter><section><section><para>
2232 #: best-pkging-practices.dbk:1595
2233 msgid ""
2234 "For example, with <literal>--guess-dummy</literal>, "
2235 "<command>deborphan</command> tries to search all transitional packages which "
2236 "were needed for upgrade but which can now safely be removed.  For that, it "
2237 "looks for the string dummy or transitional in their short description."
2238 msgstr ""
2239
2240 #. type: Content of: <chapter><section><section><para>
2241 #: best-pkging-practices.dbk:1602
2242 msgid ""
2243 "So, when you are creating such a package, please make sure to add this text "
2244 "to your short description.  If you are looking for examples, just run: "
2245 "<command>apt-cache search .|grep dummy</command> or <command>apt-cache "
2246 "search .|grep transitional</command>."
2247 msgstr ""
2248
2249 #. type: Content of: <chapter><section><section><para>
2250 #: best-pkging-practices.dbk:1608
2251 msgid ""
2252 "Also, it is recommended to adjust its section to <literal>oldlibs</literal> "
2253 "and its priority to <literal>extra</literal> in order to ease "
2254 "<command>deborphan</command>'s job."
2255 msgstr ""
2256
2257 #. type: Content of: <chapter><section><section><title>
2258 #: best-pkging-practices.dbk:1617
2259 msgid "Best practices for <filename>.orig.tar.{gz,bz2,xz}</filename> files"
2260 msgstr ""
2261
2262 #. type: Content of: <chapter><section><section><para>
2263 #: best-pkging-practices.dbk:1619
2264 msgid ""
2265 "There are two kinds of original source tarballs: Pristine source and "
2266 "repackaged upstream source."
2267 msgstr ""
2268
2269 #. type: Content of: <chapter><section><section><section><title>
2270 #: best-pkging-practices.dbk:1623
2271 msgid "Pristine source"
2272 msgstr ""
2273
2274 #. type: Content of: <chapter><section><section><section><para><footnote><para>
2275 #: best-pkging-practices.dbk:1627
2276 msgid ""
2277 "We cannot prevent upstream authors from changing the tarball they distribute "
2278 "without also incrementing the version number, so there can be no guarantee "
2279 "that a pristine tarball is identical to what upstream "
2280 "<emphasis>currently</emphasis> distributing at any point in time.  All that "
2281 "can be expected is that it is identical to something that upstream once "
2282 "<emphasis>did</emphasis> distribute.  If a difference arises later (say, if "
2283 "upstream notice that they weren't using maximal compression in their "
2284 "original distribution and then re-<command>gzip</command> it), that's just "
2285 "too bad.  Since there is no good way to upload a new "
2286 "<filename>.orig.tar.{gz,bz2,xz}</filename> for the same version, there is "
2287 "not even any point in treating this situation as a bug."
2288 msgstr ""
2289
2290 #. type: Content of: <chapter><section><section><section><para>
2291 #: best-pkging-practices.dbk:1625
2292 msgid ""
2293 "The defining characteristic of a pristine source tarball is that the "
2294 "<filename>.orig.tar.{gz,bz2,xz}</filename> file is byte-for-byte identical "
2295 "to a tarball officially distributed by the upstream author.<placeholder "
2296 "type=\"footnote\" id=\"0\"/> This makes it possible to use checksums to "
2297 "easily verify that all changes between Debian's version and upstream's are "
2298 "contained in the Debian diff.  Also, if the original source is huge, "
2299 "upstream authors and others who already have the upstream tarball can save "
2300 "download time if they want to inspect your packaging in detail."
2301 msgstr ""
2302
2303 #. type: Content of: <chapter><section><section><section><para>
2304 #: best-pkging-practices.dbk:1645
2305 msgid ""
2306 "There is no universally accepted guidelines that upstream authors follow "
2307 "regarding to the directory structure inside their tarball, but "
2308 "<command>dpkg-source</command> is nevertheless able to deal with most "
2309 "upstream tarballs as pristine source.  Its strategy is equivalent to the "
2310 "following:"
2311 msgstr ""
2312
2313 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2314 #: best-pkging-practices.dbk:1653
2315 msgid "It unpacks the tarball in an empty temporary directory by doing"
2316 msgstr ""
2317
2318 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
2319 #: best-pkging-practices.dbk:1656
2320 #, no-wrap
2321 msgid ""
2322 "zcat "
2323 "path/to/<replaceable>packagename</replaceable>_<replaceable>upstream-version</replaceable>.orig.tar.gz "
2324 "| tar xf -\n"
2325 msgstr ""
2326
2327 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2328 #: best-pkging-practices.dbk:1661
2329 msgid ""
2330 "If, after this, the temporary directory contains nothing but one directory "
2331 "and no other files, <command>dpkg-source</command> renames that directory to "
2332 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>.  "
2333 "The name of the top-level directory in the tarball does not matter, and is "
2334 "forgotten."
2335 msgstr ""
2336
2337 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2338 #: best-pkging-practices.dbk:1670
2339 msgid ""
2340 "Otherwise, the upstream tarball must have been packaged without a common "
2341 "top-level directory (shame on the upstream author!).  In this case, "
2342 "<command>dpkg-source</command> renames the temporary directory "
2343 "<emphasis>itself</emphasis> to "
2344 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>."
2345 msgstr ""
2346
2347 #. type: Content of: <chapter><section><section><section><title>
2348 #: best-pkging-practices.dbk:1681
2349 msgid "Repackaged upstream source"
2350 msgstr ""
2351
2352 #. type: Content of: <chapter><section><section><section><para>
2353 #: best-pkging-practices.dbk:1683
2354 msgid ""
2355 "You <emphasis role=\"strong\">should</emphasis> upload packages with a "
2356 "pristine source tarball if possible, but there are various reasons why it "
2357 "might not be possible.  This is the case if upstream does not distribute the "
2358 "source as gzipped tar at all, or if upstream's tarball contains "
2359 "non-DFSG-free material that you must remove before uploading."
2360 msgstr ""
2361
2362 #. type: Content of: <chapter><section><section><section><para>
2363 #: best-pkging-practices.dbk:1690
2364 msgid ""
2365 "In these cases the developer must construct a suitable "
2366 "<filename>.orig.tar.{gz,bz2,xz}</filename> file themselves.  We refer to "
2367 "such a tarball as a repackaged upstream source.  Note that a repackaged "
2368 "upstream source is different from a Debian-native package.  A repackaged "
2369 "source still comes with Debian-specific changes in a separate "
2370 "<filename>.diff.gz</filename> or "
2371 "<filename>.debian.tar.{gz,bz2,xz}</filename> and still has a version number "
2372 "composed of <replaceable>upstream-version</replaceable> and "
2373 "<replaceable>debian-version</replaceable>."
2374 msgstr ""
2375
2376 #. type: Content of: <chapter><section><section><section><para>
2377 #: best-pkging-practices.dbk:1699
2378 msgid ""
2379 "There may be cases where it is desirable to repackage the source even though "
2380 "upstream distributes a <filename>.tar.{gz,bz2,xz}</filename> that could in "
2381 "principle be used in its pristine form.  The most obvious is if "
2382 "<emphasis>significant</emphasis> space savings can be achieved by "
2383 "recompressing the tar archive or by removing genuinely useless cruft from "
2384 "the upstream archive.  Use your own discretion here, but be prepared to "
2385 "defend your decision if you repackage source that could have been pristine."
2386 msgstr ""
2387
2388 #. type: Content of: <chapter><section><section><section><para>
2389 #: best-pkging-practices.dbk:1708
2390 msgid "A repackaged <filename>.orig.tar.{gz,bz2,xz}</filename>"
2391 msgstr ""
2392
2393 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2394 #: best-pkging-practices.dbk:1713
2395 msgid ""
2396 "<emphasis role=\"strong\">should</emphasis> be documented in the resulting "
2397 "source package.  Detailed information on how the repackaged source was "
2398 "obtained, and on how this can be reproduced should be provided in "
2399 "<filename>debian/copyright</filename>.  It is also a good idea to provide a "
2400 "<literal>get-orig-source</literal> target in your "
2401 "<filename>debian/rules</filename> file that repeats the process, as "
2402 "described in the Policy Manual, <ulink "
2403 "url=\"&url-debian-policy;ch-source.html#s-debianrules\">Main building "
2404 "script: <filename>debian/rules</filename></ulink>."
2405 msgstr ""
2406
2407 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
2408 #: best-pkging-practices.dbk:1728
2409 msgid ""
2410 "As a special exception, if the omission of non-free files would lead to the "
2411 "source failing to build without assistance from the Debian diff, it might be "
2412 "appropriate to instead edit the files, omitting only the non-free parts of "
2413 "them, and/or explain the situation in a <filename>README.source</filename> "
2414 "file in the root of the source tree.  But in that case please also urge the "
2415 "upstream author to make the non-free components easier separable from the "
2416 "rest of the source."
2417 msgstr ""
2418
2419 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2420 #: best-pkging-practices.dbk:1726
2421 msgid ""
2422 "<emphasis role=\"strong\">should not</emphasis> contain any file that does "
2423 "not come from the upstream author(s), or whose contents has been changed by "
2424 "you.<placeholder type=\"footnote\" id=\"0\"/>"
2425 msgstr ""
2426
2427 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2428 #: best-pkging-practices.dbk:1739
2429 msgid ""
2430 "<emphasis role=\"strong\">should</emphasis>, except where impossible for "
2431 "legal reasons, preserve the entire building and portablility infrastructure "
2432 "provided by the upstream author.  For example, it is not a sufficient reason "
2433 "for omitting a file that it is used only when building on MS-DOS.  "
2434 "Similarly, a <filename>Makefile</filename> provided by upstream should not "
2435 "be omitted even if the first thing your <filename>debian/rules</filename> "
2436 "does is to overwrite it by running a configure script."
2437 msgstr ""
2438
2439 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2440 #: best-pkging-practices.dbk:1748
2441 msgid ""
2442 "(<emphasis>Rationale:</emphasis> It is common for Debian users who need to "
2443 "build software for non-Debian platforms to fetch the source from a Debian "
2444 "mirror rather than trying to locate a canonical upstream distribution "
2445 "point)."
2446 msgstr ""
2447
2448 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2449 #: best-pkging-practices.dbk:1755
2450 msgid ""
2451 "<emphasis role=\"strong\">should</emphasis> use "
2452 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>.orig</filename> "
2453 "as the name of the top-level directory in its tarball.  This makes it "
2454 "possible to distinguish pristine tarballs from repackaged ones."
2455 msgstr ""
2456
2457 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2458 #: best-pkging-practices.dbk:1763
2459 msgid ""
2460 "<emphasis role=\"strong\">should</emphasis> be gzipped or bzipped with "
2461 "maximal compression."
2462 msgstr ""
2463
2464 #. type: Content of: <chapter><section><section><section><title>
2465 #: best-pkging-practices.dbk:1770
2466 msgid "Changing binary files"
2467 msgstr ""
2468
2469 #. type: Content of: <chapter><section><section><section><para>
2470 #: best-pkging-practices.dbk:1772
2471 msgid ""
2472 "Sometimes it is necessary to change binary files contained in the original "
2473 "tarball, or to add binary files that are not in it. This is fully supported "
2474 "when using source packages in “3.0 (quilt)” format, see the "
2475 "<citerefentry><refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum></citerefentry> "
2476 "manual page for details. When using the older format “1.0”, binary files "
2477 "can't be stored in the <filename>.diff.gz</filename> so you must store an "
2478 "<command>uuencode</command>d (or similar) version of the file(s)  and decode "
2479 "it at build time in <filename>debian/rules</filename> (and move it in its "
2480 "official location)."
2481 msgstr ""
2482
2483 #. type: Content of: <chapter><section><section><title>
2484 #: best-pkging-practices.dbk:1787
2485 msgid "Best practices for debug packages"
2486 msgstr ""
2487
2488 #. type: Content of: <chapter><section><section><para>
2489 #: best-pkging-practices.dbk:1789
2490 msgid ""
2491 "A debug package is a package with a name ending in -dbg, that contains "
2492 "additional information that <command>gdb</command> can use.  Since Debian "
2493 "binaries are stripped by default, debugging information, including function "
2494 "names and line numbers, is otherwise not available when running "
2495 "<command>gdb</command> on Debian binaries.  Debug packages allow users who "
2496 "need this additional debugging information to install it, without bloating a "
2497 "regular system with the information."
2498 msgstr ""
2499
2500 #. type: Content of: <chapter><section><section><para>
2501 #: best-pkging-practices.dbk:1797
2502 msgid ""
2503 "It is up to a package's maintainer whether to create a debug package or "
2504 "not.  Maintainers are encouraged to create debug packages for library "
2505 "packages, since this can aid in debugging many programs linked to a "
2506 "library.  In general, debug packages do not need to be added for all "
2507 "programs; doing so would bloat the archive.  But if a maintainer finds that "
2508 "users often need a debugging version of a program, it can be worthwhile to "
2509 "make a debug package for it.  Programs that are core infrastructure, such as "
2510 "apache and the X server are also good candidates for debug packages."
2511 msgstr ""
2512
2513 #. type: Content of: <chapter><section><section><para>
2514 #: best-pkging-practices.dbk:1807
2515 msgid ""
2516 "Some debug packages may contain an entire special debugging build of a "
2517 "library or other binary, but most of them can save space and build time by "
2518 "instead containing separated debugging symbols that <command>gdb</command> "
2519 "can find and load on the fly when debugging a program or library.  The "
2520 "convention in Debian is to keep these symbols in "
2521 "<filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where "
2522 "<replaceable>path</replaceable> is the path to the executable or library.  "
2523 "For example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
2524 "<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for "
2525 "<filename>/usr/lib/libfoo.so.1</filename> go in "
2526 "<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>."
2527 msgstr ""
2528
2529 #. type: Content of: <chapter><section><section><para>
2530 #: best-pkging-practices.dbk:1819
2531 msgid ""
2532 "The debugging symbols can be extracted from an object file using "
2533 "<command>objcopy --only-keep-debug</command>.  Then the object file can be "
2534 "stripped, and <command>objcopy --add-gnu-debuglink</command> used to specify "
2535 "the path to the debugging symbol file.  <citerefentry> "
2536 "<refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum> "
2537 "</citerefentry> explains in detail how this works."
2538 msgstr ""
2539
2540 #. type: Content of: <chapter><section><section><para>
2541 #: best-pkging-practices.dbk:1827
2542 msgid ""
2543 "The <command>dh_strip</command> command in <systemitem "
2544 "role=\"package\">debhelper</systemitem> supports creating debug packages, "
2545 "and can take care of using <command>objcopy</command> to separate out the "
2546 "debugging symbols for you.  If your package uses <systemitem "
2547 "role=\"package\">debhelper</systemitem>, all you need to do is call "
2548 "<command>dh_strip --dbg-package=libfoo-dbg</command>, and add an entry to "
2549 "<filename>debian/control</filename> for the debug package."
2550 msgstr ""
2551
2552 #. type: Content of: <chapter><section><section><para>
2553 #: best-pkging-practices.dbk:1834
2554 msgid ""
2555 "Note that the debug package should depend on the package that it provides "
2556 "debugging symbols for, and this dependency should be versioned.  For "
2557 "example:"
2558 msgstr ""
2559
2560 #. type: Content of: <chapter><section><section><screen>
2561 #: best-pkging-practices.dbk:1838
2562 #, no-wrap
2563 msgid "Depends: libfoo (= ${binary:Version})\n"
2564 msgstr ""
2565
2566 #. type: Content of: <chapter><section><section><title>
2567 #: best-pkging-practices.dbk:1842
2568 msgid "Best practices for meta-packages"
2569 msgstr ""
2570
2571 #. type: Content of: <chapter><section><section><para>
2572 #: best-pkging-practices.dbk:1844
2573 msgid ""
2574 "A meta-package is a mostly empty package that makes it easy to install a "
2575 "coherent set of packages that can evolve over time. It achieves this by "
2576 "depending on all the packages of the set. Thanks to the power of APT, the "
2577 "meta-package maintainer can adjust the dependencies and the user's system "
2578 "will automatically get the supplementary packages. The dropped packages that "
2579 "were automatically installed will be also be marked as removal candidates "
2580 "(and are even automatically removed by <command>aptitude</command>).  "
2581 "<systemitem role=\"package\">gnome</systemitem> and <systemitem "
2582 "role=\"package\">linux-image-amd64</systemitem> are two examples of "
2583 "meta-packages (built by the source packages <systemitem "
2584 "role=\"package\">meta-gnome2</systemitem> and <systemitem "
2585 "role=\"package\">linux-latest</systemitem>)."
2586 msgstr ""
2587
2588 #. type: Content of: <chapter><section><section><para>
2589 #: best-pkging-practices.dbk:1858
2590 msgid ""
2591 "The long description of the meta-package must clearly document its purpose "
2592 "so that the user knows what they will lose if they remove the package. Being "
2593 "explicit about the consequences is recommended. This is particularly "
2594 "important for meta-packages which are installed during initial installation "
2595 "and that have not been explicitly installed by the user.  Those tend to be "
2596 "important to ensure smooth system upgrades and the user should be "
2597 "discouraged from uninstalling them to avoid potential breakages."
2598 msgstr ""
2599
2600 #. type: Content of: <chapter><title>
2601 #: beyond-pkging.dbk:7
2602 msgid "Beyond Packaging"
2603 msgstr ""
2604
2605 #. type: Content of: <chapter><para>
2606 #: beyond-pkging.dbk:9
2607 msgid ""
2608 "Debian is about a lot more than just packaging software and maintaining "
2609 "those packages.  This chapter contains information about ways, often really "
2610 "critical ways, to contribute to Debian beyond simply creating and "
2611 "maintaining packages."
2612 msgstr ""
2613
2614 #. type: Content of: <chapter><para>
2615 #: beyond-pkging.dbk:14
2616 msgid ""
2617 "As a volunteer organization, Debian relies on the discretion of its members "
2618 "in choosing what they want to work on and in choosing the most critical "
2619 "thing to spend their time on."
2620 msgstr ""
2621
2622 #. type: Content of: <chapter><section><title>
2623 #: beyond-pkging.dbk:19
2624 msgid "Bug reporting"
2625 msgstr ""
2626
2627 #. type: Content of: <chapter><section><para>
2628 #: beyond-pkging.dbk:21
2629 msgid ""
2630 "We encourage you to file bugs as you find them in Debian packages.  In fact, "
2631 "Debian developers are often the first line testers.  Finding and reporting "
2632 "bugs in other developers' packages improves the quality of Debian."
2633 msgstr ""
2634
2635 #. type: Content of: <chapter><section><para>
2636 #: beyond-pkging.dbk:26
2637 msgid ""
2638 "Read the <ulink url=\"&url-bts-report;\">instructions for reporting "
2639 "bugs</ulink> in the Debian <ulink url=\"&url-bts;\">bug tracking "
2640 "system</ulink>."
2641 msgstr ""
2642
2643 #. type: Content of: <chapter><section><para>
2644 #: beyond-pkging.dbk:31
2645 msgid ""
2646 "Try to submit the bug from a normal user account at which you are likely to "
2647 "receive mail, so that people can reach you if they need further information "
2648 "about the bug.  Do not submit bugs as root."
2649 msgstr ""
2650
2651 #. type: Content of: <chapter><section><para>
2652 #: beyond-pkging.dbk:36
2653 msgid ""
2654 "You can use a tool like <citerefentry> "
2655 "<refentrytitle>reportbug</refentrytitle> <manvolnum>1</manvolnum> "
2656 "</citerefentry> to submit bugs.  It can automate and generally ease the "
2657 "process."
2658 msgstr ""
2659
2660 #. type: Content of: <chapter><section><para>
2661 #: beyond-pkging.dbk:41
2662 msgid ""
2663 "Make sure the bug is not already filed against a package.  Each package has "
2664 "a bug list easily reachable at "
2665 "<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>.  "
2666 "Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle> "
2667 "<manvolnum>1</manvolnum> </citerefentry> can also provide you with this "
2668 "information (and <command>reportbug</command> will usually invoke "
2669 "<command>querybts</command> before sending, too)."
2670 msgstr ""
2671
2672 #. type: Content of: <chapter><section><para>
2673 #: beyond-pkging.dbk:50
2674 msgid ""
2675 "Try to direct your bugs to the proper location.  When for example your bug "
2676 "is about a package which overwrites files from another package, check the "
2677 "bug lists for <emphasis>both</emphasis> of those packages in order to avoid "
2678 "filing duplicate bug reports."
2679 msgstr ""
2680
2681 #. type: Content of: <chapter><section><para>
2682 #: beyond-pkging.dbk:56
2683 msgid ""
2684 "For extra credit, you can go through other packages, merging bugs which are "
2685 "reported more than once, or tagging bugs `fixed' when they have already been "
2686 "fixed.  Note that when you are neither the bug submitter nor the package "
2687 "maintainer, you should not actually close the bug (unless you secure "
2688 "permission from the maintainer)."
2689 msgstr ""
2690
2691 #. type: Content of: <chapter><section><para>
2692 #: beyond-pkging.dbk:63
2693 msgid ""
2694 "From time to time you may want to check what has been going on with the bug "
2695 "reports that you submitted.  Take this opportunity to close those that you "
2696 "can't reproduce anymore.  To find out all the bugs you submitted, you just "
2697 "have to visit "
2698 "<literal>http://&bugs-host;/from:<replaceable>your-email-addr</replaceable></literal>."
2699 msgstr ""
2700
2701 #. type: Content of: <chapter><section><section><title>
2702 #: beyond-pkging.dbk:70
2703 msgid "Reporting lots of bugs at once (mass bug filing)"
2704 msgstr ""
2705
2706 #. type: Content of: <chapter><section><section><para>
2707 #: beyond-pkging.dbk:72
2708 msgid ""
2709 "Reporting a great number of bugs for the same problem on a great number of "
2710 "different packages — i.e., more than 10 — is a deprecated practice.  Take "
2711 "all possible steps to avoid submitting bulk bugs at all.  For instance, if "
2712 "checking for the problem can be automated, add a new check to <systemitem "
2713 "role=\"package\">lintian</systemitem> so that an error or warning is "
2714 "emitted."
2715 msgstr ""
2716
2717 #. type: Content of: <chapter><section><section><para>
2718 #: beyond-pkging.dbk:79
2719 msgid ""
2720 "If you report more than 10 bugs on the same topic at once, it is recommended "
2721 "that you send a message to &email-debian-devel; describing your intention "
2722 "before submitting the report, and mentioning the fact in the subject of your "
2723 "mail.  This will allow other developers to verify that the bug is a real "
2724 "problem.  In addition, it will help prevent a situation in which several "
2725 "maintainers start filing the same bug report simultaneously."
2726 msgstr ""
2727
2728 #. type: Content of: <chapter><section><section><para>
2729 #: beyond-pkging.dbk:87
2730 msgid ""
2731 "Please use the programs <command>dd-list</command> and if appropriate "
2732 "<command>whodepends</command> (from the package <systemitem "
2733 "role=\"package\">devscripts</systemitem>) to generate a list of all affected "
2734 "packages, and include the output in your mail to &email-debian-devel;."
2735 msgstr ""
2736
2737 #. type: Content of: <chapter><section><section><para>
2738 #: beyond-pkging.dbk:93
2739 msgid ""
2740 "Note that when sending lots of bugs on the same subject, you should send the "
2741 "bug report to <email>maintonly@&bugs-host;</email> so that the bug report is "
2742 "not forwarded to the bug distribution mailing list."
2743 msgstr ""
2744
2745 #. type: Content of: <chapter><section><section><section><title>
2746 #: beyond-pkging.dbk:98
2747 msgid "Usertags"
2748 msgstr ""
2749
2750 #. type: Content of: <chapter><section><section><section><para>
2751 #: beyond-pkging.dbk:100
2752 msgid ""
2753 "You may wish to use BTS usertags when submitting bugs across a number of "
2754 "packages. Usertags are similar to normal tags such as 'patch' and 'wishlist' "
2755 "but differ in that they are user-defined and occupy a namespace that is "
2756 "unique to a particular user. This allows multiple sets of developers to "
2757 "'usertag' the same bug in different ways without conflicting."
2758 msgstr ""
2759
2760 #. type: Content of: <chapter><section><section><section><para>
2761 #: beyond-pkging.dbk:107
2762 msgid ""
2763 "To add usertags when filing bugs, specify the <literal>User</literal> and "
2764 "<literal>Usertags</literal> pseudo-headers:"
2765 msgstr ""
2766
2767 #. type: Content of: <chapter><section><section><section><screen>
2768 #: beyond-pkging.dbk:111
2769 #, no-wrap
2770 msgid ""
2771 "To: submit@bugs.debian.org\n"
2772 "Subject: <replaceable>title-of-bug</replaceable>\n"
2773 "\n"
2774 "Package: <replaceable>pkgname</replaceable>\n"
2775 "<replaceable>[ ... ]</replaceable>\n"
2776 "User: <replaceable>email-addr</replaceable>\n"
2777 "Usertags: <replaceable>tag-name [ tag-name ... ]</replaceable>\n"
2778 "\n"
2779 "<replaceable>description-of-bug ...</replaceable>\n"
2780 msgstr ""
2781
2782 #. type: Content of: <chapter><section><section><section><para>
2783 #: beyond-pkging.dbk:122
2784 msgid ""
2785 "Note that tags are seperated by spaces and cannot contain underscores. If "
2786 "you are filing bugs for a particular group or team it is recommended that "
2787 "you set the <literal>User</literal> to an appropriate mailing list after "
2788 "describing your intention there."
2789 msgstr ""
2790
2791 #. type: Content of: <chapter><section><section><section><para>
2792 #: beyond-pkging.dbk:128
2793 msgid ""
2794 "To view bugs tagged with a specific usertag, visit "
2795 "<literal>http://&bugs-host;/cgi-bin/pkgreport.cgi?users=<replaceable>email-addr</replaceable>&amp;tag=<replaceable>tag-name</replaceable></literal>."
2796 msgstr ""
2797
2798 #. type: Content of: <chapter><section><title>
2799 #: beyond-pkging.dbk:137
2800 msgid "Quality Assurance effort"
2801 msgstr ""
2802
2803 #. type: Content of: <chapter><section><section><title>
2804 #: beyond-pkging.dbk:139
2805 msgid "Daily work"
2806 msgstr ""
2807
2808 #. type: Content of: <chapter><section><section><para>
2809 #: beyond-pkging.dbk:141
2810 msgid ""
2811 "Even though there is a dedicated group of people for Quality Assurance, QA "
2812 "duties are not reserved solely for them.  You can participate in this effort "
2813 "by keeping your packages as bug-free as possible, and as lintian-clean (see "
2814 "<xref linkend=\"lintian\"/>) as possible.  If you do not find that possible, "
2815 "then you should consider orphaning some of your packages (see <xref "
2816 "linkend=\"orphaning\"/>).  Alternatively, you may ask the help of other "
2817 "people in order to catch up with the backlog of bugs that you have (you can "
2818 "ask for help on &email-debian-qa; or &email-debian-devel;).  At the same "
2819 "time, you can look for co-maintainers (see <xref "
2820 "linkend=\"collaborative-maint\"/>)."
2821 msgstr ""
2822
2823 #. type: Content of: <chapter><section><section><title>
2824 #: beyond-pkging.dbk:155
2825 msgid "Bug squashing parties"
2826 msgstr ""
2827
2828 #. type: Content of: <chapter><section><section><para>
2829 #: beyond-pkging.dbk:157
2830 msgid ""
2831 "From time to time the QA group organizes bug squashing parties to get rid of "
2832 "as many problems as possible.  They are announced on "
2833 "&email-debian-devel-announce; and the announcement explains which area will "
2834 "be the focus of the party: usually they focus on release critical bugs but "
2835 "it may happen that they decide to help finish a major upgrade (like a new "
2836 "<command>perl</command> version which requires recompilation of all the "
2837 "binary modules)."
2838 msgstr ""
2839
2840 #. type: Content of: <chapter><section><section><para>
2841 #: beyond-pkging.dbk:166
2842 msgid ""
2843 "The rules for non-maintainer uploads differ during the parties because the "
2844 "announcement of the party is considered prior notice for NMU.  If you have "
2845 "packages that may be affected by the party (because they have release "
2846 "critical bugs for example), you should send an update to each of the "
2847 "corresponding bug to explain their current status and what you expect from "
2848 "the party.  If you don't want an NMU, or if you're only interested in a "
2849 "patch, or if you will deal yourself with the bug, please explain that in the "
2850 "BTS."
2851 msgstr ""
2852
2853 #. type: Content of: <chapter><section><section><para>
2854 #: beyond-pkging.dbk:175
2855 msgid ""
2856 "People participating in the party have special rules for NMU, they can NMU "
2857 "without prior notice if they upload their NMU to DELAYED/3-day at least.  "
2858 "All other NMU rules apply as usually; they should send the patch of the NMU "
2859 "to the BTS (to one of the open bugs fixed by the NMU, or to a new bug, "
2860 "tagged fixed).  They should also respect any particular wishes of the "
2861 "maintainer."
2862 msgstr ""
2863
2864 #. type: Content of: <chapter><section><section><para>
2865 #: beyond-pkging.dbk:182
2866 msgid ""
2867 "If you don't feel confident about doing an NMU, just send a patch to the "
2868 "BTS.  It's far better than a broken NMU."
2869 msgstr ""
2870
2871 #. type: Content of: <chapter><section><title>
2872 #: beyond-pkging.dbk:190
2873 msgid "Contacting other maintainers"
2874 msgstr ""
2875
2876 #. type: Content of: <chapter><section><para>
2877 #: beyond-pkging.dbk:192
2878 msgid ""
2879 "During your lifetime within Debian, you will have to contact other "
2880 "maintainers for various reasons.  You may want to discuss a new way of "
2881 "cooperating between a set of related packages, or you may simply remind "
2882 "someone that a new upstream version is available and that you need it."
2883 msgstr ""
2884
2885 #. type: Content of: <chapter><section><para>
2886 #: beyond-pkging.dbk:198
2887 msgid ""
2888 "Looking up the email address of the maintainer for the package can be "
2889 "distracting.  Fortunately, there is a simple email alias, "
2890 "<literal><replaceable>package</replaceable>@&packages-host;</literal>, which "
2891 "provides a way to email the maintainer, whatever their individual email "
2892 "address (or addresses)  may be.  Replace <replaceable>package</replaceable> "
2893 "with the name of a source or a binary package."
2894 msgstr ""
2895
2896 #. type: Content of: <chapter><section><para>
2897 #: beyond-pkging.dbk:206
2898 msgid ""
2899 "You may also be interested in contacting the persons who are subscribed to a "
2900 "given source package via <xref linkend=\"pkg-tracking-system\"/>.  You can "
2901 "do so by using the "
2902 "<literal><replaceable>package</replaceable>@&pts-host;</literal> email "
2903 "address."
2904 msgstr ""
2905
2906 #. type: Content of: <chapter><section><title>
2907 #: beyond-pkging.dbk:215
2908 msgid "Dealing with inactive and/or unreachable maintainers"
2909 msgstr ""
2910
2911 #. type: Content of: <chapter><section><para>
2912 #: beyond-pkging.dbk:217
2913 msgid ""
2914 "If you notice that a package is lacking maintenance, you should make sure "
2915 "that the maintainer is active and will continue to work on their packages.  "
2916 "It is possible that they are not active any more, but haven't registered out "
2917 "of the system, so to speak.  On the other hand, it is also possible that "
2918 "they just need a reminder."
2919 msgstr ""
2920
2921 #. type: Content of: <chapter><section><para>
2922 #: beyond-pkging.dbk:224
2923 msgid ""
2924 "There is a simple system (the MIA database) in which information about "
2925 "maintainers who are deemed Missing In Action is recorded.  When a member of "
2926 "the QA group contacts an inactive maintainer or finds more information about "
2927 "one, this is recorded in the MIA database.  This system is available in "
2928 "<filename>/org/qa.debian.org/mia</filename> on the host "
2929 "<literal>qa.debian.org</literal>, and can be queried with the "
2930 "<command>mia-query</command> tool.  Use <command>mia-query --help</command> "
2931 "to see how to query the database.  If you find that no information has been "
2932 "recorded about an inactive maintainer yet, or that you can add more "
2933 "information, you should generally proceed as follows."
2934 msgstr ""
2935
2936 #. type: Content of: <chapter><section><para>
2937 #: beyond-pkging.dbk:235
2938 msgid ""
2939 "The first step is to politely contact the maintainer, and wait a reasonable "
2940 "time for a response.  It is quite hard to define reasonable time, but it is "
2941 "important to take into account that real life is sometimes very hectic.  One "
2942 "way to handle this would be to send a reminder after two weeks."
2943 msgstr ""
2944
2945 #. type: Content of: <chapter><section><para>
2946 #: beyond-pkging.dbk:241
2947 msgid ""
2948 "If the maintainer doesn't reply within four weeks (a month), one can assume "
2949 "that a response will probably not happen.  If that happens, you should "
2950 "investigate further, and try to gather as much useful information about the "
2951 "maintainer in question as possible.  This includes:"
2952 msgstr ""
2953
2954 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
2955 #: beyond-pkging.dbk:249
2956 msgid ""
2957 "The <literal>echelon</literal> information available through the <ulink "
2958 "url=\"&url-debian-db;\">developers' LDAP database</ulink>, which indicates "
2959 "when the developer last posted to a Debian mailing list.  (This includes "
2960 "mails about uploads distributed via the &email-debian-devel-changes; list.)  "
2961 "Also, remember to check whether the maintainer is marked as on vacation in "
2962 "the database."
2963 msgstr ""
2964
2965 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
2966 #: beyond-pkging.dbk:259
2967 msgid ""
2968 "The number of packages this maintainer is responsible for, and the condition "
2969 "of those packages.  In particular, are there any RC bugs that have been open "
2970 "for ages? Furthermore, how many bugs are there in general? Another important "
2971 "piece of information is whether the packages have been NMUed, and if so, by "
2972 "whom."
2973 msgstr ""
2974
2975 #. type: Content of: <chapter><section><itemizedlist><listitem><para>
2976 #: beyond-pkging.dbk:268
2977 msgid ""
2978 "Is there any activity of the maintainer outside of Debian? For example, they "
2979 "might have posted something recently to non-Debian mailing lists or news "
2980 "groups."
2981 msgstr ""
2982
2983 #. type: Content of: <chapter><section><para>
2984 #: beyond-pkging.dbk:275
2985 msgid ""
2986 "A bit of a problem are packages which were sponsored — the maintainer is not "
2987 "an official Debian developer.  The <literal>echelon</literal> information is "
2988 "not available for sponsored people, for example, so you need to find and "
2989 "contact the Debian developer who has actually uploaded the package.  Given "
2990 "that they signed the package, they're responsible for the upload anyhow, and "
2991 "are likely to know what happened to the person they sponsored."
2992 msgstr ""
2993
2994 #. type: Content of: <chapter><section><para>
2995 #: beyond-pkging.dbk:283
2996 msgid ""
2997 "It is also allowed to post a query to &email-debian-devel;, asking if anyone "
2998 "is aware of the whereabouts of the missing maintainer.  Please Cc: the "
2999 "person in question."
3000 msgstr ""
3001
3002 #. type: Content of: <chapter><section><para>
3003 #: beyond-pkging.dbk:288
3004 msgid ""
3005 "Once you have gathered all of this, you can contact &email-mia;.  People on "
3006 "this alias will use the information you provide in order to decide how to "
3007 "proceed.  For example, they might orphan one or all of the packages of the "
3008 "maintainer.  If a package has been NMUed, they might prefer to contact the "
3009 "NMUer before orphaning the package — perhaps the person who has done the NMU "
3010 "is interested in the package."
3011 msgstr ""
3012
3013 #. type: Content of: <chapter><section><para>
3014 #: beyond-pkging.dbk:296
3015 msgid ""
3016 "One last word: please remember to be polite.  We are all volunteers and "
3017 "cannot dedicate all of our time to Debian.  Also, you are not aware of the "
3018 "circumstances of the person who is involved.  Perhaps they might be "
3019 "seriously ill or might even have died — you do not know who may be on the "
3020 "receiving side.  Imagine how a relative will feel if they read the e-mail of "
3021 "the deceased and find a very impolite, angry and accusing message!"
3022 msgstr ""
3023
3024 #. type: Content of: <chapter><section><para>
3025 #: beyond-pkging.dbk:304
3026 msgid ""
3027 "On the other hand, although we are volunteers, we do have a responsibility.  "
3028 "So you can stress the importance of the greater good — if a maintainer does "
3029 "not have the time or interest anymore, they should let go and give the "
3030 "package to someone with more time."
3031 msgstr ""
3032
3033 #. type: Content of: <chapter><section><para>
3034 #: beyond-pkging.dbk:310
3035 msgid ""
3036 "If you are interested in working in the MIA team, please have a look at the "
3037 "<filename>README</filename> file in "
3038 "<filename>/org/qa.debian.org/mia</filename> on "
3039 "<literal>qa.debian.org</literal> where the technical details and the MIA "
3040 "procedures are documented and contact &email-mia;."
3041 msgstr ""
3042
3043 #. type: Content of: <chapter><section><title>
3044 #: beyond-pkging.dbk:318
3045 msgid "Interacting with prospective Debian developers"
3046 msgstr ""
3047
3048 #. type: Content of: <chapter><section><para>
3049 #: beyond-pkging.dbk:320
3050 msgid ""
3051 "Debian's success depends on its ability to attract and retain new and "
3052 "talented volunteers.  If you are an experienced developer, we recommend that "
3053 "you get involved with the process of bringing in new developers.  This "
3054 "section describes how to help new prospective developers."
3055 msgstr ""
3056
3057 #. type: Content of: <chapter><section><section><title>
3058 #: beyond-pkging.dbk:326
3059 msgid "Sponsoring packages"
3060 msgstr ""
3061
3062 #. type: Content of: <chapter><section><section><para>
3063 #: beyond-pkging.dbk:328
3064 msgid ""
3065 "Sponsoring a package means uploading a package for a maintainer who is not "
3066 "able to do it on their own. It's not a trivial matter, the sponsor must "
3067 "verify the packaging and ensure that it is of the high level of quality that "
3068 "Debian strives to have."
3069 msgstr ""
3070
3071 #. type: Content of: <chapter><section><section><para>
3072 #: beyond-pkging.dbk:334
3073 msgid "Debian Developers can sponsor packages. Debian Maintainers can't."
3074 msgstr ""
3075
3076 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
3077 #: beyond-pkging.dbk:340
3078 msgid ""
3079 "The maintainer prepares a source package (<filename>.dsc</filename>) and "
3080 "puts it online somewhere (like on <ulink "
3081 "url=\"http://mentors.debian.net/cgi-bin/welcome\">mentors.debian.net</ulink>) "
3082 "or even better, provides a link to a public VCS repository (see <xref "
3083 "linkend=\"servers-vcs\"/>) where the package is maintained."
3084 msgstr ""
3085
3086 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
3087 #: beyond-pkging.dbk:346
3088 msgid "The sponsor downloads (or checkouts) the source package."
3089 msgstr ""
3090
3091 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
3092 #: beyond-pkging.dbk:349
3093 msgid ""
3094 "The sponsor reviews the source package. If they find issues, they inform the "
3095 "maintainer and ask them to provide a fixed version (the process starts over "
3096 "at step 1)."
3097 msgstr ""
3098
3099 #. type: Content of: <chapter><section><section><para><orderedlist><listitem><para>
3100 #: beyond-pkging.dbk:354
3101 msgid ""
3102 "The sponsor could not find any remaining problem. They build the package, "
3103 "sign it, and upload it to Debian."
3104 msgstr ""
3105
3106 #. type: Content of: <chapter><section><section><para>
3107 #: beyond-pkging.dbk:337
3108 msgid ""
3109 "The process of sponsoring a package is: <placeholder type=\"orderedlist\" "
3110 "id=\"0\"/>"
3111 msgstr ""
3112
3113 #. type: Content of: <chapter><section><section><para>
3114 #: beyond-pkging.dbk:360
3115 msgid ""
3116 "Before delving in the details of how to sponsor a package, you should ask "
3117 "yourself whether adding the proposed package is beneficial to Debian."
3118 msgstr ""
3119
3120 #. type: Content of: <chapter><section><section><para>
3121 #: beyond-pkging.dbk:364
3122 msgid ""
3123 "There's no simple rule to answer this question, it can depend on many "
3124 "factors: is the upstream codebase mature and not full of security holes? Are "
3125 "there pre-existing packages that can do the same task and how do they "
3126 "compare to this new package? Has the new package been requested by users and "
3127 "how large is the user base? How active are the upstream developers?"
3128 msgstr ""
3129
3130 #. type: Content of: <chapter><section><section><para>
3131 #: beyond-pkging.dbk:371
3132 msgid ""
3133 "You should also ensure that the prospective maintainer is going to be a good "
3134 "maintainer. Do they already have some experience with other packages? If "
3135 "yes, are they doing a good job with them (check out some bugs)? Are they "
3136 "familiar with the package and its programming language? Do they have the "
3137 "skills needed for this package? If not, are they able to learn them?"
3138 msgstr ""
3139
3140 #. type: Content of: <chapter><section><section><para>
3141 #: beyond-pkging.dbk:379
3142 msgid ""
3143 "It's also a good idea to know where they stand with respect to Debian: do "
3144 "they agree with Debian's philosophy and do they intend to join Debian? Given "
3145 "how easy it is to become a Debian Maintainer, you might want to only sponsor "
3146 "people who plan to join. That way you know from the start that you won't "
3147 "have to act as a sponsor indefinitely."
3148 msgstr ""
3149
3150 #. type: Content of: <chapter><section><section><section><title>
3151 #: beyond-pkging.dbk:386
3152 msgid "Sponsoring a new package"
3153 msgstr ""
3154
3155 #. type: Content of: <chapter><section><section><section><para>
3156 #: beyond-pkging.dbk:388
3157 msgid ""
3158 "New maintainers usually have certain difficulties creating Debian packages — "
3159 "this is quite understandable. They will do mistakes. That's why sponsoring a "
3160 "brand new package into Debian requires a thorough review of the Debian "
3161 "packaging. Sometimes several iterations will be needed until the package is "
3162 "good enough to be uploaded to Debian. Thus being a sponsor implies being a "
3163 "mentor."
3164 msgstr ""
3165
3166 #. type: Content of: <chapter><section><section><section><para>
3167 #: beyond-pkging.dbk:396
3168 msgid ""
3169 "Don't ever sponsor a new package without reviewing it. The review of new "
3170 "packages done by ftpmasters mainly ensures that the software is really "
3171 "free. Of course, it happens that they stumble on packaging problems but they "
3172 "really should not. It's your task to ensure that the uploaded package "
3173 "complies with the Debian Free Software Guidelines and is of good quality."
3174 msgstr ""
3175
3176 #. type: Content of: <chapter><section><section><section><para><footnote><para>
3177 #: beyond-pkging.dbk:409
3178 msgid ""
3179 "You can find more checks in the wiki where several developers share their "
3180 "own <ulink url=\"http://wiki.debian.org/SponsorChecklist\">sponsorship "
3181 "checklists</ulink>."
3182 msgstr ""
3183
3184 #. type: Content of: <chapter><section><section><section><para>
3185 #: beyond-pkging.dbk:404
3186 msgid ""
3187 "Building the package and testing the software is part of the review, but "
3188 "it's also not enough. The rest of this section contains a non-exhaustive "
3189 "list of points to check in your review.  <placeholder type=\"footnote\" "
3190 "id=\"0\"/>"
3191 msgstr ""
3192
3193 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3194 #: beyond-pkging.dbk:416
3195 msgid ""
3196 "Verify that the upstream tarball provided is the same that has been "
3197 "distributed by the upstream author (when the sources are repackaged for "
3198 "Debian, generate the modified tarball yourself)."
3199 msgstr ""
3200
3201 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3202 #: beyond-pkging.dbk:421
3203 msgid ""
3204 "Run <command>lintian</command> (see <xref linkend=\"lintian\"/>). It will "
3205 "catch many common problems. Be sure to verify that any "
3206 "<command>lintian</command> overrides setup by the maintainer is fully "
3207 "justified."
3208 msgstr ""
3209
3210 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3211 #: beyond-pkging.dbk:426
3212 msgid ""
3213 "Run <command>licensecheck</command> (part of <xref linkend=\"devscripts\"/>) "
3214 "and verify that <filename>debian/copyright</filename> seems correct and "
3215 "complete. Look for license problems (like files with “All rights reserved” "
3216 "headers, or with a non-DFSG compliant license). <command>grep -ri</command> "
3217 "is your friend for this task."
3218 msgstr ""
3219
3220 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3221 #: beyond-pkging.dbk:433
3222 msgid ""
3223 "Build the package with <command>pbuilder</command> (or any similar tool, see "
3224 "<xref linkend=\"pbuilder\"/>) to ensure that the build-dependencies are "
3225 "complete."
3226 msgstr ""
3227
3228 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3229 #: beyond-pkging.dbk:438
3230 msgid ""
3231 "Proofread <filename>debian/control</filename>: does it follow the best "
3232 "practices (see <xref linkend=\"bpp-debian-control\"/>)? Are the dependencies "
3233 "complete?"
3234 msgstr ""
3235
3236 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3237 #: beyond-pkging.dbk:443
3238 msgid ""
3239 "Proofread <filename>debian/rules</filename>: does it follow the best "
3240 "practices (see <xref linkend=\"bpp-debian-rules\"/>)? Do you see some "
3241 "possible improvements?"
3242 msgstr ""
3243
3244 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3245 #: beyond-pkging.dbk:448
3246 msgid ""
3247 "Proofread the maintainer scripts (<filename>preinst</filename>, "
3248 "<filename>postinst</filename>, <filename>prerm</filename>, "
3249 "<filename>postrm</filename>, <filename>config</filename>): will the "
3250 "<filename>preinst</filename>/<filename>postrm</filename> work when the "
3251 "dependencies are not installed? Are all the scripts idempotent (i.e. can you "
3252 "run them multiple times without consequences)?"
3253 msgstr ""
3254
3255 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3256 #: beyond-pkging.dbk:456
3257 msgid ""
3258 "Review any change to upstream files (either in "
3259 "<filename>.diff.gz</filename>, or in <filename>debian/patches/</filename> or "
3260 "directly embedded in the <filename>debian</filename> tarball for binary "
3261 "files). Are they justified? Are they properly documented (with <ulink "
3262 "url=\"&url-dep3;\">DEP-3</ulink> for patches)?"
3263 msgstr ""
3264
3265 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3266 #: beyond-pkging.dbk:462
3267 msgid ""
3268 "For every file, ask yourself why the file is there and whether it's the "
3269 "right way to achieve the desired result. Is the maintainer following the "
3270 "best packaging practices (see <xref linkend=\"best-pkging-practices\"/>)?"
3271 msgstr ""
3272
3273 #. type: Content of: <chapter><section><section><section><itemizedlist><listitem><para>
3274 #: beyond-pkging.dbk:468
3275 msgid ""
3276 "Build the packages, install them and try the software. Ensure you can remove "
3277 "and purge the packages. Maybe test them with <command>piuparts</command>."
3278 msgstr ""
3279
3280 #. type: Content of: <chapter><section><section><section><para>
3281 #: beyond-pkging.dbk:474
3282 msgid ""
3283 "If the audit did not reveal any problem, you can build the package and "
3284 "upload it to Debian. Remember that even if you're not the maintainer, as a "
3285 "sponsor you are still responsible for what you upload to Debian. That's why "
3286 "you're encouraged to keep up with the package through the <xref "
3287 "linkend=\"pkg-tracking-system\"/>."
3288 msgstr ""
3289
3290 #. type: Content of: <chapter><section><section><section><para>
3291 #: beyond-pkging.dbk:481
3292 msgid ""
3293 "Note that you should not need to modify the source package to put your name "
3294 "in the <filename>changelog</filename> or in the <filename>control</filename> "
3295 "file. The <literal>Maintainer</literal> field of the "
3296 "<filename>control</filename> file and the <filename>changelog</filename> "
3297 "should list the person who did the packaging, i.e. the sponsoree. That way "
3298 "they will get all the BTS mail."
3299 msgstr ""
3300
3301 #. type: Content of: <chapter><section><section><section><para>
3302 #: beyond-pkging.dbk:487
3303 msgid ""
3304 "Instead you should instruct <command>dpkg-buildpackage</command> to use your "
3305 "key for the signature. You do that with the <literal>-k</literal> option:"
3306 msgstr ""
3307
3308 #. type: Content of: <chapter><section><section><section><screen>
3309 #: beyond-pkging.dbk:490
3310 #, no-wrap
3311 msgid "dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>\n"
3312 msgstr ""
3313
3314 #. type: Content of: <chapter><section><section><section><para>
3315 #: beyond-pkging.dbk:492
3316 msgid ""
3317 "If you use <command>debuild</command> and <command>debsign</command>, you "
3318 "can even configure it permanently in <filename>~/.devscripts</filename>:"
3319 msgstr ""
3320
3321 #. type: Content of: <chapter><section><section><section><programlisting>
3322 #: beyond-pkging.dbk:495
3323 #, no-wrap
3324 msgid "DEBSIGN_KEYID=<replaceable>KEY-ID</replaceable>\n"
3325 msgstr ""
3326
3327 #. type: Content of: <chapter><section><section><section><title>
3328 #: beyond-pkging.dbk:500
3329 msgid "Sponsoring an update of an existing package"
3330 msgstr ""
3331
3332 #. type: Content of: <chapter><section><section><section><para>
3333 #: beyond-pkging.dbk:502
3334 msgid ""
3335 "You will usually assume that the package has already gone through a full "
3336 "review. So instead of doing it again, you will carefully analyze the "
3337 "difference between the current version and the new version prepared by the "
3338 "maintainer. If you have not done the initial review yourself, you might "
3339 "still want to have a more deeper look just in case the initial reviewer was "
3340 "sloppy."
3341 msgstr ""
3342
3343 #. type: Content of: <chapter><section><section><section><para>
3344 #: beyond-pkging.dbk:510
3345 msgid ""
3346 "To be able to analyze the difference you need both versions. Download the "
3347 "current version of the source package (with <command>apt-get "
3348 "source</command>)  and rebuild it (or download the current binary packages "
3349 "with <command>aptitude download</command>). Download the source package to "
3350 "sponsor (usually with <command>dget</command>)."
3351 msgstr ""
3352
3353 #. type: Content of: <chapter><section><section><section><para>
3354 #: beyond-pkging.dbk:517
3355 msgid ""
3356 "Read the new changelog entry, it should tell you what to expect during the "
3357 "review. The main tool you will use is <command>debdiff</command> (provide by "
3358 "the <systemitem role=\"package\">devscripts</systemitem> package), you can "
3359 "run it with two source packages (<filename>.dsc</filename> files), or two "
3360 "binary packages, or two <filename>.changes</filename> files (it will then "
3361 "compare all the binary packages listed in the "
3362 "<filename>.changes</filename>)."
3363 msgstr ""
3364
3365 #. type: Content of: <chapter><section><section><section><para>
3366 #: beyond-pkging.dbk:524
3367 msgid ""
3368 "If you compare the source packages (excluding upstream files in the case of "
3369 "a new upstream version, for example by filtering the output of "
3370 "<command>debdiff</command> with <command>filterdiff -i "
3371 "'*/debian/*'</command>), you must understand all the changes you see and "
3372 "they should be properly documented in the Debian changelog."
3373 msgstr ""
3374
3375 #. type: Content of: <chapter><section><section><section><para>
3376 #: beyond-pkging.dbk:531
3377 msgid ""
3378 "If everything is fine, build the package and compare the binary packages to "
3379 "verify that the changes on the source package have no unexpected "
3380 "consequences (like some files dropped by mistake, missing dependencies, "
3381 "etc.)."
3382 msgstr ""
3383
3384 #. type: Content of: <chapter><section><section><section><para>
3385 #: beyond-pkging.dbk:537
3386 msgid ""
3387 "You might want to check out the Package Tracking System (see <xref "
3388 "linkend=\"pkg-tracking-system\"/>) to verify if the maintainer has not "
3389 "missed something important. Maybe there are translations updates sitting in "
3390 "the BTS that could have been integrated. Maybe the package has been NMUed "
3391 "and the maintainer forgot to integrate the changes from the NMU into their "
3392 "package. Maybe there's a release critical bug that they have left unhandled "
3393 "and that's blocking migration to <literal>testing</literal>.  If you find "
3394 "something that they could have done (better), it's time to tell them so that "
3395 "they can improve for next time, and so that they have a better understanding "
3396 "of their responsibilities."
3397 msgstr ""
3398
3399 #. type: Content of: <chapter><section><section><section><para>
3400 #: beyond-pkging.dbk:549
3401 msgid ""
3402 "If you have found no major problem, upload the new version. Otherwise ask "
3403 "the maintainer to provide you a fixed version."
3404 msgstr ""
3405
3406 #. type: Content of: <chapter><section><section><title>
3407 #: beyond-pkging.dbk:556
3408 msgid "Advocating new developers"
3409 msgstr ""
3410
3411 #. type: Content of: <chapter><section><section><para>
3412 #: beyond-pkging.dbk:558
3413 msgid ""
3414 "See the page about <ulink url=\"&url-newmaint-advocate;\">advocating a "
3415 "prospective developer</ulink> at the Debian web site."
3416 msgstr ""
3417
3418 #. type: Content of: <chapter><section><section><title>
3419 #: beyond-pkging.dbk:565
3420 msgid "Handling new maintainer applications"
3421 msgstr ""
3422
3423 #. type: Content of: <chapter><section><section><para>
3424 #: beyond-pkging.dbk:567
3425 msgid ""
3426 "Please see <ulink url=\"&url-newmaint-amchecklist;\">Checklist for "
3427 "Application Managers</ulink> at the Debian web site."
3428 msgstr ""
3429
3430 #. type: Content of: <chapter><title>
3431 #: developer-duties.dbk:7
3432 msgid "Debian Developer's Duties"
3433 msgstr ""
3434
3435 #. type: Content of: <chapter><section><title>
3436 #: developer-duties.dbk:10
3437 msgid "Package Maintainer's Duties"
3438 msgstr ""
3439
3440 #. type: Content of: <chapter><section><para>
3441 #: developer-duties.dbk:11
3442 msgid ""
3443 "As a package maintainer, you're supposed to provide high-quality packages "
3444 "that are well integrated in the system and that adhere to the Debian Policy."
3445 msgstr ""
3446
3447 #. type: Content of: <chapter><section><section><title>
3448 #: developer-duties.dbk:16
3449 msgid "Work towards the next <literal>stable</literal> release"
3450 msgstr ""
3451
3452 #. type: Content of: <chapter><section><section><para>
3453 #: developer-duties.dbk:18
3454 msgid ""
3455 "Providing high-quality packages in <literal>unstable</literal> is not "
3456 "enough, most users will only benefit from your packages when they are "
3457 "released as part of the next <literal>stable</literal> release. You are thus "
3458 "expected to collaborate with the release team to ensure your packages get "
3459 "included."
3460 msgstr ""
3461
3462 #. type: Content of: <chapter><section><section><para>
3463 #: developer-duties.dbk:24
3464 msgid ""
3465 "More concretely, you should monitor whether your packages are migrating to "
3466 "<literal>testing</literal> (see <xref linkend=\"testing\"/>). When the "
3467 "migration doesn't happen after the test period, you should analyze why and "
3468 "work towards fixing this.  It might mean fixing your package (in the case of "
3469 "release-critical bugs or failures to build on some architecture) but it can "
3470 "also mean updating (or fixing, or removing from <literal>testing</literal>) "
3471 "other packages to help complete a transition in which your package is "
3472 "entangled due to its dependencies. The release team might provide you some "
3473 "input on the current blockers of a given transition if you are not able to "
3474 "identify them."
3475 msgstr ""
3476
3477 #. type: Content of: <chapter><section><section><title>
3478 #: developer-duties.dbk:37
3479 msgid "Maintain packages in <literal>stable</literal>"
3480 msgstr ""
3481
3482 #. type: Content of: <chapter><section><section><para>
3483 #: developer-duties.dbk:39
3484 msgid ""
3485 "Most of the package maintainer's work goes into providing updated versions "
3486 "of packages in <literal>unstable</literal>, but their job also entails "
3487 "taking care of the packages in the current <literal>stable</literal> "
3488 "release."
3489 msgstr ""
3490
3491 #. type: Content of: <chapter><section><section><para>
3492 #: developer-duties.dbk:44
3493 msgid ""
3494 "While changes in <literal>stable</literal> are discouraged, they are "
3495 "possible. Whenever a security problem is reported, you should collaborate "
3496 "with the security team to provide a fixed version (see <xref "
3497 "linkend=\"bug-security\"/>). When bugs of severity important (or more) are "
3498 "reported against the <literal>stable</literal> version of your packages, you "
3499 "should consider providing a targeted fix.  You can ask the "
3500 "<literal>stable</literal> release team whether they would accept such an "
3501 "update and then prepare a <literal>stable</literal> upload (see <xref "
3502 "linkend=\"upload-stable\"/>)."
3503 msgstr ""
3504
3505 #. type: Content of: <chapter><section><section><title>
3506 #: developer-duties.dbk:56
3507 msgid "Manage release-critical bugs"
3508 msgstr ""
3509
3510 #. type: Content of: <chapter><section><section><para>
3511 #: developer-duties.dbk:58
3512 msgid ""
3513 "Generally you should deal with bug reports on your packages as described in "
3514 "<xref linkend=\"bug-handling\"/>.  However, there's a special category of "
3515 "bugs that you need to take care of — the so-called release-critical bugs (RC "
3516 "bugs). All bug reports that have severity <literal>critical</literal>, "
3517 "<literal>grave</literal> or <literal>serious</literal> make the package "
3518 "unsuitable for inclusion in the next <literal>stable</literal> release.  "
3519 "They can thus delay the Debian release (when they affect a package in "
3520 "<literal>testing</literal>) or block migrations to "
3521 "<literal>testing</literal> (when they only affect the package in "
3522 "<literal>unstable</literal>). In the worst scenario, they will lead to the "
3523 "package's removal. That's why these bugs need to be corrected as quickly as "
3524 "possible."
3525 msgstr ""
3526
3527 #. type: Content of: <chapter><section><section><para>
3528 #: developer-duties.dbk:70
3529 msgid ""
3530 "If, for any reason, you aren't able fix an RC bug in a package of yours "
3531 "within 2 weeks (for example due to time constraints, or because it's "
3532 "difficult to fix), you should mention it clearly in the bug report and you "
3533 "should tag the bug <literal>help</literal> to invite other volunteers to "
3534 "chime in. Be aware that RC bugs are frequently the targets of Non-Maintainer "
3535 "Uploads (see <xref linkend=\"nmu\"/>) because they can block the "
3536 "<literal>testing</literal> migration of many packages."
3537 msgstr ""
3538
3539 #. type: Content of: <chapter><section><section><para>
3540 #: developer-duties.dbk:79
3541 msgid ""
3542 "Lack of attention to RC bugs is often interpreted by the QA team as a sign "
3543 "that the maintainer has disappeared without properly orphaning their "
3544 "package.  The MIA team might also get involved, which could result in your "
3545 "packages being orphaned (see <xref linkend=\"mia-qa\" />)."
3546 msgstr ""
3547
3548 #. type: Content of: <chapter><section><section><title>
3549 #: developer-duties.dbk:87
3550 msgid "Coordination with upstream developers"
3551 msgstr ""
3552
3553 #. type: Content of: <chapter><section><section><para>
3554 #: developer-duties.dbk:89
3555 msgid ""
3556 "A big part of your job as Debian maintainer will be to stay in contact with "
3557 "the upstream developers.  Debian users will sometimes report bugs that are "
3558 "not specific to Debian to our bug tracking system.  You have to forward "
3559 "these bug reports to the upstream developers so that they can be fixed in a "
3560 "future upstream release."
3561 msgstr ""
3562
3563 #. type: Content of: <chapter><section><section><para>
3564 #: developer-duties.dbk:96
3565 msgid ""
3566 "While it's not your job to fix non-Debian specific bugs, you may freely do "
3567 "so if you're able.  When you make such fixes, be sure to pass them on to the "
3568 "upstream maintainers as well.  Debian users and developers will sometimes "
3569 "submit patches to fix upstream bugs — you should evaluate and forward these "
3570 "patches upstream."
3571 msgstr ""
3572
3573 #. type: Content of: <chapter><section><section><para>
3574 #: developer-duties.dbk:103
3575 msgid ""
3576 "If you need to modify the upstream sources in order to build a policy "
3577 "compliant package, then you should propose a nice fix to the upstream "
3578 "developers which can be included there, so that you won't have to modify the "
3579 "sources of the next upstream version.  Whatever changes you need, always try "
3580 "not to fork from the upstream sources."
3581 msgstr ""
3582
3583 #. type: Content of: <chapter><section><section><para>
3584 #: developer-duties.dbk:110
3585 msgid ""
3586 "If you find that the upstream developers are or become hostile towards "
3587 "Debian or the free software community, you may want to re-consider the need "
3588 "to include the software in Debian. Sometimes the social cost to the Debian "
3589 "community is not worth the benefits the software may bring."
3590 msgstr ""
3591
3592 #. type: Content of: <chapter><section><title>
3593 #: developer-duties.dbk:120
3594 msgid "Administrative Duties"
3595 msgstr ""
3596
3597 #. type: Content of: <chapter><section><para>
3598 #: developer-duties.dbk:121
3599 msgid ""
3600 "A project of the size of Debian relies on some administrative infrastructure "
3601 "to keep track of everything. As a project member, you have some duties to "
3602 "ensure everything keeps running smoothly."
3603 msgstr ""
3604
3605 #. type: Content of: <chapter><section><section><title>
3606 #: developer-duties.dbk:126
3607 msgid "Maintaining your Debian information"
3608 msgstr ""
3609
3610 #. type: Content of: <chapter><section><section><para>
3611 #: developer-duties.dbk:128
3612 msgid ""
3613 "There's a LDAP database containing information about Debian developers at "
3614 "<ulink url=\"&url-debian-db;\"></ulink>.  You should enter your information "
3615 "there and update it as it changes.  Most notably, make sure that the address "
3616 "where your debian.org email gets forwarded to is always up to date, as well "
3617 "as the address where you get your debian-private subscription if you choose "
3618 "to subscribe there."
3619 msgstr ""
3620
3621 #. type: Content of: <chapter><section><section><para>
3622 #: developer-duties.dbk:136
3623 msgid ""
3624 "For more information about the database, please see <xref "
3625 "linkend=\"devel-db\"/>."
3626 msgstr ""
3627
3628 #. type: Content of: <chapter><section><section><title>
3629 #: developer-duties.dbk:141
3630 msgid "Maintaining your public key"
3631 msgstr ""
3632
3633 #. type: Content of: <chapter><section><section><para>
3634 #: developer-duties.dbk:143
3635 msgid ""
3636 "Be very careful with your private keys.  Do not place them on any public "
3637 "servers or multiuser machines, such as the Debian servers (see <xref "
3638 "linkend=\"server-machines\"/>).  Back your keys up; keep a copy offline.  "
3639 "Read the documentation that comes with your software; read the <ulink "
3640 "url=\"&url-pgp-faq;\">PGP FAQ</ulink>."
3641 msgstr ""
3642
3643 #. type: Content of: <chapter><section><section><para>
3644 #: developer-duties.dbk:150
3645 msgid ""
3646 "You need to ensure not only that your key is secure against being stolen, "
3647 "but also that it is secure against being lost.  Generate and make a copy "
3648 "(best also in paper form) of your revocation certificate; this is needed if "
3649 "your key is lost."
3650 msgstr ""
3651
3652 #. type: Content of: <chapter><section><section><para>
3653 #: developer-duties.dbk:156
3654 msgid ""
3655 "If you add signatures to your public key, or add user identities, you can "
3656 "update the Debian key ring by sending your key to the key server at "
3657 "<literal>&keyserver-host;</literal>."
3658 msgstr ""
3659
3660 #. type: Content of: <chapter><section><section><para>
3661 #: developer-duties.dbk:161
3662 msgid ""
3663 "If you need to add a completely new key or remove an old key, you need to "
3664 "get the new key signed by another developer.  If the old key is compromised "
3665 "or invalid, you also have to add the revocation certificate.  If there is no "
3666 "real reason for a new key, the Keyring Maintainers might reject the new "
3667 "key.  Details can be found at <ulink "
3668 "url=\"http://&keyserver-host;/replacing_keys.html\"></ulink>."
3669 msgstr ""
3670
3671 #. type: Content of: <chapter><section><section><para>
3672 #: developer-duties.dbk:169
3673 msgid ""
3674 "The same key extraction routines discussed in <xref "
3675 "linkend=\"registering\"/> apply."
3676 msgstr ""
3677
3678 #. type: Content of: <chapter><section><section><para>
3679 #: developer-duties.dbk:173
3680 msgid ""
3681 "You can find a more in-depth discussion of Debian key maintenance in the "
3682 "documentation of the <systemitem "
3683 "role=\"package\">debian-keyring</systemitem> package."
3684 msgstr ""
3685
3686 #. type: Content of: <chapter><section><section><title>
3687 #: developer-duties.dbk:180
3688 msgid "Voting"
3689 msgstr ""
3690
3691 #. type: Content of: <chapter><section><section><para>
3692 #: developer-duties.dbk:182
3693 msgid ""
3694 "Even though Debian isn't really a democracy, we use a democratic process to "
3695 "elect our leaders and to approve general resolutions.  These procedures are "
3696 "defined by the <ulink url=\"&url-constitution;\">Debian "
3697 "Constitution</ulink>."
3698 msgstr ""
3699
3700 #. type: Content of: <chapter><section><section><para>
3701 #: developer-duties.dbk:188
3702 msgid ""
3703 "Other than the yearly leader election, votes are not routinely held, and "
3704 "they are not undertaken lightly.  Each proposal is first discussed on the "
3705 "&email-debian-vote; mailing list and it requires several endorsements before "
3706 "the project secretary starts the voting procedure."
3707 msgstr ""
3708
3709 #. type: Content of: <chapter><section><section><para>
3710 #: developer-duties.dbk:194
3711 msgid ""
3712 "You don't have to track the pre-vote discussions, as the secretary will "
3713 "issue several calls for votes on &email-debian-devel-announce; (and all "
3714 "developers are expected to be subscribed to that list).  Democracy doesn't "
3715 "work well if people don't take part in the vote, which is why we encourage "
3716 "all developers to vote.  Voting is conducted via GPG-signed/encrypted email "
3717 "messages."
3718 msgstr ""
3719
3720 #. type: Content of: <chapter><section><section><para>
3721 #: developer-duties.dbk:202
3722 msgid ""
3723 "The list of all proposals (past and current) is available on the <ulink "
3724 "url=\"&url-vote;\">Debian Voting Information</ulink> page, along with "
3725 "information on how to make, second and vote on proposals."
3726 msgstr ""
3727
3728 #. type: Content of: <chapter><section><section><title>
3729 #: developer-duties.dbk:209
3730 msgid "Going on vacation gracefully"
3731 msgstr ""
3732