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