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.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2011-09-10 14:01-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"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
19 #. type: Content of: <chapter><title>
20 #: best-pkging-practices.dbk:7
21 msgid "Best Packaging Practices"
24 #. type: Content of: <chapter><para>
25 #: best-pkging-practices.dbk:9
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."
36 #. type: Content of: <chapter><para>
37 #: best-pkging-practices.dbk:18
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."
45 #. type: Content of: <chapter><section><title>
46 #: best-pkging-practices.dbk:24
47 msgid "Best practices for <filename>debian/rules</filename>"
50 #. type: Content of: <chapter><section><para>
51 #: best-pkging-practices.dbk:26
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."
59 #. type: Content of: <chapter><section><section><title>
60 #: best-pkging-practices.dbk:32
61 msgid "Helper scripts"
64 #. type: Content of: <chapter><section><section><para>
65 #: best-pkging-practices.dbk:34
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 "
79 #. type: Content of: <chapter><section><section><para>
80 #: best-pkging-practices.dbk:45
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 "
89 #. type: Content of: <chapter><section><section><para>
90 #: best-pkging-practices.dbk:52
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>."
107 #. type: Content of: <chapter><section><section><para>
108 #: best-pkging-practices.dbk:66
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."
123 #. type: Content of: <chapter><section><section><para>
124 #: best-pkging-practices.dbk:79
126 "Some people feel that vanilla <filename>debian/rules</filename> files are "
127 "better, since you don't have to learn the intricacies of any helper system. "
128 "This decision is completely up to you. Use what works for you. Many "
129 "examples of vanilla <filename>debian/rules</filename> files are available at "
130 "<ulink url=\"&url-rules-files;\"></ulink>."
133 #. type: Content of: <chapter><section><section><title>
134 #: best-pkging-practices.dbk:88
135 msgid "Separating your patches into multiple files"
138 #. type: Content of: <chapter><section><section><para>
139 #: best-pkging-practices.dbk:90
141 "Big, complex packages may have many bugs that you need to deal with. If you "
142 "correct a number of bugs directly in the source, and you're not careful, it "
143 "can get hard to differentiate the various patches that you applied. It can "
144 "get quite messy when you have to update the package to a new upstream "
145 "version which integrates some of the fixes (but not all). You can't take "
146 "the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
147 "out which patch sets to back out as a unit as bugs are fixed upstream."
150 #. type: Content of: <chapter><section><section><para>
151 #: best-pkging-practices.dbk:99
153 "Fortunately, with the source format “3.0 (quilt)” it is now possible to keep "
154 "patches separate without having to modify <filename>debian/rules</filename> "
155 "to setup a patch system. Patches are stored in "
156 "<filename>debian/patches/</filename> and when the source package is unpacked "
157 "patches listed in <filename>debian/patches/series</filename> are "
158 "automatically applied. As the name implies, patches can be managed with "
159 "<command>quilt</command>."
162 #. type: Content of: <chapter><section><section><para>
163 #: best-pkging-practices.dbk:107
165 "When using the older source “1.0”, it's also possible to separate patches "
166 "but a dedicated patch system must be used: the patch files are shipped "
167 "within the Debian patch file (<filename>.diff.gz</filename>), usually within "
168 "the <filename>debian/</filename> directory. The only difference is that they "
169 "aren't applied immediately by <command>dpkg-source</command>, but by the "
170 "<literal>build</literal> rule of <filename>debian/rules</filename>, through "
171 "a dependency on the <literal>patch</literal> rule. Conversely, they are "
172 "reverted in the <literal>clean</literal> rule, through a dependency on the "
173 "<literal>unpatch</literal> rule."
176 #. type: Content of: <chapter><section><section><para>
177 #: best-pkging-practices.dbk:119
179 "<command>quilt</command> is the recommended tool for this. It does all of "
180 "the above, and also allows to manage patch series. See the <systemitem "
181 "role=\"package\">quilt</systemitem> package for more information."
184 #. type: Content of: <chapter><section><section><para>
185 #: best-pkging-practices.dbk:125
187 "There are other tools to manage patches, like <command>dpatch</command>, and "
188 "the patch system integrated with <systemitem "
189 "role=\"package\">cdbs</systemitem>."
192 #. type: Content of: <chapter><section><section><title>
193 #: best-pkging-practices.dbk:132
194 msgid "Multiple binary packages"
197 #. type: Content of: <chapter><section><section><para>
198 #: best-pkging-practices.dbk:134
200 "A single source package will often build several binary packages, either to "
201 "provide several flavors of the same software (e.g., the <systemitem "
202 "role=\"package\">vim</systemitem> source package) or to make several small "
203 "packages instead of a big one (e.g., so the user can install only the subset "
204 "needed, and thus save some disk space)."
207 #. type: Content of: <chapter><section><section><para>
208 #: best-pkging-practices.dbk:141
210 "The second case can be easily managed in <filename>debian/rules</filename>. "
211 "You just need to move the appropriate files from the build directory into "
212 "the package's temporary trees. You can do this using "
213 "<command>install</command> or <command>dh_install</command> from <systemitem "
214 "role=\"package\">debhelper</systemitem>. Be sure to check the different "
215 "permutations of the various packages, ensuring that you have the "
216 "inter-package dependencies set right in <filename>debian/control</filename>."
219 #. type: Content of: <chapter><section><section><para>
220 #: best-pkging-practices.dbk:150
222 "The first case is a bit more difficult since it involves multiple recompiles "
223 "of the same software but with different configuration options. The "
224 "<systemitem role=\"package\">vim</systemitem> source package is an example "
225 "of how to manage this using an hand-crafted "
226 "<filename>debian/rules</filename> file."
229 #. type: Content of: <chapter><section><title>
230 #: best-pkging-practices.dbk:162
231 msgid "Best practices for <filename>debian/control</filename>"
234 #. type: Content of: <chapter><section><para>
235 #: best-pkging-practices.dbk:164
237 "The following practices are relevant to the "
238 "<filename>debian/control</filename> file. They supplement the <ulink "
239 "url=\"&url-debian-policy;ch-binary.html#s-descriptions\">Policy on package "
240 "descriptions</ulink>."
243 #. type: Content of: <chapter><section><para>
244 #: best-pkging-practices.dbk:170
246 "The description of the package, as defined by the corresponding field in the "
247 "<filename>control</filename> file, contains both the package synopsis and "
248 "the long description for the package. <xref linkend=\"bpp-desc-basics\"/> "
249 "describes common guidelines for both parts of the package description. "
250 "Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
251 "specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
252 "guidelines specific to the description."
255 #. type: Content of: <chapter><section><section><title>
256 #: best-pkging-practices.dbk:179
257 msgid "General guidelines for package descriptions"
260 #. type: Content of: <chapter><section><section><para>
261 #: best-pkging-practices.dbk:181
263 "The package description should be written for the average likely user, the "
264 "average person who will use and benefit from the package. For instance, "
265 "development packages are for developers, and can be technical in their "
266 "language. More general-purpose applications, such as editors, should be "
267 "written for a less technical user."
270 #. type: Content of: <chapter><section><section><para>
271 #: best-pkging-practices.dbk:188
273 "Our review of package descriptions lead us to conclude that most package "
274 "descriptions are technical, that is, are not written to make sense for "
275 "non-technical users. Unless your package really is only for technical "
276 "users, this is a problem."
279 #. type: Content of: <chapter><section><section><para>
280 #: best-pkging-practices.dbk:194
282 "How do you write for non-technical users? Avoid jargon. Avoid referring to "
283 "other applications or frameworks that the user might not be familiar with — "
284 "GNOME or KDE is fine, since users are probably familiar with these terms, "
285 "but GTK+ is probably not. Try not to assume any knowledge at all. If you "
286 "must use technical terms, introduce them."
289 #. type: Content of: <chapter><section><section><para>
290 #: best-pkging-practices.dbk:201
292 "Be objective. Package descriptions are not the place for advocating your "
293 "package, no matter how much you love it. Remember that the reader may not "
294 "care about the same things you care about."
297 #. type: Content of: <chapter><section><section><para>
298 #: best-pkging-practices.dbk:206
300 "References to the names of any other software packages, protocol names, "
301 "standards, or specifications should use their canonical forms, if one "
302 "exists. For example, use X Window System, X11, or X; not X Windows, "
303 "X-Windows, or X Window. Use GTK+, not GTK or gtk. Use GNOME, not Gnome. "
304 "Use PostScript, not Postscript or postscript."
307 #. type: Content of: <chapter><section><section><para>
308 #: best-pkging-practices.dbk:213
310 "If you are having problems writing your description, you may wish to send it "
311 "along to &email-debian-l10n-english; and request feedback."
314 #. type: Content of: <chapter><section><section><title>
315 #: best-pkging-practices.dbk:219
316 msgid "The package synopsis, or short description"
319 #. type: Content of: <chapter><section><section><para>
320 #: best-pkging-practices.dbk:221
322 "Policy says the synopsis line (the short description) must be concise, not "
323 "repeating the package name, but also informative."
326 #. type: Content of: <chapter><section><section><para>
327 #: best-pkging-practices.dbk:225
329 "The synopsis functions as a phrase describing the package, not a complete "
330 "sentence, so sentential punctuation is inappropriate: it does not need extra "
331 "capital letters or a final period (full stop). It should also omit any "
332 "initial indefinite or definite article — \"a\", \"an\", or \"the\". Thus for "
336 #. type: Content of: <chapter><section><section><screen>
337 #: best-pkging-practices.dbk:231
341 "Description: exemplification support library\n"
344 #. type: Content of: <chapter><section><section><para>
345 #: best-pkging-practices.dbk:235
347 "Technically this is a noun phrase minus articles, as opposed to a verb "
348 "phrase. A good heuristic is that it should be possible to substitute the "
349 "package <replaceable>name</replaceable> and "
350 "<replaceable>synopsis</replaceable> into this formula:"
353 #. type: Content of: <chapter><section><section><para>
354 #: best-pkging-practices.dbk:240
356 "The package <replaceable>name</replaceable> provides {a,an,the,some} "
357 "<replaceable>synopsis</replaceable>."
360 #. type: Content of: <chapter><section><section><para>
361 #: best-pkging-practices.dbk:244
363 "Sets of related packages may use an alternative scheme that divides the "
364 "synopsis into two parts, the first a description of the whole suite and the "
365 "second a summary of the package's role within it:"
368 #. type: Content of: <chapter><section><section><screen>
369 #: best-pkging-practices.dbk:249
372 "Package: eg-tools\n"
373 "Description: simple exemplification system (utilities)\n"
376 "Description: simple exemplification system - documentation\n"
379 #. type: Content of: <chapter><section><section><para>
380 #: best-pkging-practices.dbk:256
382 "These synopses follow a modified formula. Where a package "
383 "\"<replaceable>name</replaceable>\" has a synopsis "
384 "\"<replaceable>suite</replaceable> (<replaceable>role</replaceable>)\" or "
385 "\"<replaceable>suite</replaceable> - <replaceable>role</replaceable>\", the "
386 "elements should be phrased so that they fit into the formula:"
389 #. type: Content of: <chapter><section><section><para>
390 #: best-pkging-practices.dbk:263
392 "The package <replaceable>name</replaceable> provides {a,an,the} "
393 "<replaceable>role</replaceable> for the <replaceable>suite</replaceable>."
396 #. type: Content of: <chapter><section><section><title>
397 #: best-pkging-practices.dbk:269
398 msgid "The long description"
401 #. type: Content of: <chapter><section><section><para>
402 #: best-pkging-practices.dbk:271
404 "The long description is the primary information available to the user about "
405 "a package before they install it. It should provide all the information "
406 "needed to let the user decide whether to install the package. Assume that "
407 "the user has already read the package synopsis."
410 #. type: Content of: <chapter><section><section><para>
411 #: best-pkging-practices.dbk:277
412 msgid "The long description should consist of full and complete sentences."
415 #. type: Content of: <chapter><section><section><para>
416 #: best-pkging-practices.dbk:280
418 "The first paragraph of the long description should answer the following "
419 "questions: what does the package do? what task does it help the user "
420 "accomplish? It is important to describe this in a non-technical way, unless "
421 "of course the audience for the package is necessarily technical."
424 #. type: Content of: <chapter><section><section><para>
425 #: best-pkging-practices.dbk:286
427 "The following paragraphs should answer the following questions: Why do I as "
428 "a user need this package? What other features does the package have? What "
429 "outstanding features and deficiencies are there compared to other packages "
430 "(e.g., if you need X, use Y instead)? Is this package related to other "
431 "packages in some way that is not handled by the package manager (e.g., this "
432 "is the client for the foo server)?"
435 #. type: Content of: <chapter><section><section><para>
436 #: best-pkging-practices.dbk:294
438 "Be careful to avoid spelling and grammar mistakes. Ensure that you "
439 "spell-check it. Both <command>ispell</command> and "
440 "<command>aspell</command> have special modes for checking "
441 "<filename>debian/control</filename> files:"
444 #. type: Content of: <chapter><section><section><screen>
445 #: best-pkging-practices.dbk:299
447 msgid "ispell -d american -g debian/control\n"
450 #. type: Content of: <chapter><section><section><screen>
451 #: best-pkging-practices.dbk:302
453 msgid "aspell -d en -D -c debian/control\n"
456 #. type: Content of: <chapter><section><section><para>
457 #: best-pkging-practices.dbk:305
459 "Users usually expect these questions to be answered in the package "
463 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
464 #: best-pkging-practices.dbk:310
466 "What does the package do? If it is an add-on to another package, then the "
467 "short description of the package we are an add-on to should be put in here."
470 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
471 #: best-pkging-practices.dbk:316
473 "Why should I want this package? This is related to the above, but not the "
474 "same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
475 "LDAP and IMAP, has features X, Y, and Z)."
478 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
479 #: best-pkging-practices.dbk:323
481 "If this package should not be installed directly, but is pulled in by "
482 "another package, this should be mentioned."
485 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
486 #: best-pkging-practices.dbk:329
488 "If the package is <literal>experimental</literal>, or there are other "
489 "reasons it should not be used, if there are other packages that should be "
490 "used instead, it should be here as well."
493 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
494 #: best-pkging-practices.dbk:336
496 "How is this package different from the competition? Is it a better "
497 "implementation? more features? different features? Why should I choose this "
501 #. type: Content of: <chapter><section><section><title>
502 #: best-pkging-practices.dbk:349
503 msgid "Upstream home page"
506 #. type: Content of: <chapter><section><section><para>
507 #: best-pkging-practices.dbk:351
509 "We recommend that you add the URL for the package's home page in the "
510 "<literal>Homepage</literal> field of the <literal>Source</literal> section "
511 "in <filename>debian/control</filename>. Adding this information in the "
512 "package description itself is considered deprecated."
515 #. type: Content of: <chapter><section><section><title>
516 #: best-pkging-practices.dbk:359
517 msgid "Version Control System location"
520 #. type: Content of: <chapter><section><section><para>
521 #: best-pkging-practices.dbk:361
523 "There are additional fields for the location of the Version Control System "
524 "in <filename>debian/control</filename>."
527 #. type: Content of: <chapter><section><section><section><title>
528 #: best-pkging-practices.dbk:365
532 #. type: Content of: <chapter><section><section><section><para>
533 #: best-pkging-practices.dbk:367
535 "Value of this field should be a <literal>http://</literal> URL pointing to a "
536 "web-browsable copy of the Version Control System repository used to maintain "
537 "the given package, if available."
540 #. type: Content of: <chapter><section><section><section><para>
541 #: best-pkging-practices.dbk:372
543 "The information is meant to be useful for the final user, willing to browse "
544 "the latest work done on the package (e.g. when looking for the patch fixing "
545 "a bug tagged as <literal>pending</literal> in the bug tracking system)."
548 #. type: Content of: <chapter><section><section><section><title>
549 #: best-pkging-practices.dbk:379
553 #. type: Content of: <chapter><section><section><section><para>
554 #: best-pkging-practices.dbk:381
556 "Value of this field should be a string identifying unequivocally the "
557 "location of the Version Control System repository used to maintain the given "
558 "package, if available. <literal>*</literal> identify the Version Control "
559 "System; currently the following systems are supported by the package "
560 "tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
561 "<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
562 "<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
563 "<literal>svn</literal> (Subversion). It is allowed to specify different VCS "
564 "fields for the same package: they will all be shown in the PTS web "
568 #. type: Content of: <chapter><section><section><section><para>
569 #: best-pkging-practices.dbk:392
571 "The information is meant to be useful for a user knowledgeable in the given "
572 "Version Control System and willing to build the current version of a package "
573 "from the VCS sources. Other uses of this information might include "
574 "automatic building of the latest VCS version of the given package. To this "
575 "end the location pointed to by the field should better be version agnostic "
576 "and point to the main branch (for VCSs supporting such a concept). Also, "
577 "the location pointed to should be accessible to the final user; fulfilling "
578 "this requirement might imply pointing to an anonymous access of the "
579 "repository instead of pointing to an SSH-accessible version of the same."
582 #. type: Content of: <chapter><section><section><section><para>
583 #: best-pkging-practices.dbk:403
585 "In the following example, an instance of the field for a Subversion "
586 "repository of the <systemitem role=\"package\">vim</systemitem> package is "
587 "shown. Note how the URL is in the <literal>svn://</literal> scheme (instead "
588 "of <literal>svn+ssh://</literal>) and how it points to the "
589 "<filename>trunk/</filename> branch. The use of the "
590 "<literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields "
591 "described above is also shown."
594 #. type: Content of: <chapter><section><section><section><screen>
595 #: best-pkging-practices.dbk:412
599 " Section: editors\n"
600 " Priority: optional\n"
602 " Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
603 " Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim\n"
604 " Homepage: http://www.vim.org\n"
607 #. type: Content of: <chapter><section><title>
608 #: best-pkging-practices.dbk:427
609 msgid "Best practices for <filename>debian/changelog</filename>"
612 #. type: Content of: <chapter><section><para>
613 #: best-pkging-practices.dbk:429
615 "The following practices supplement the <ulink "
616 "url=\"&url-debian-policy;ch-docs.html#s-changelogs\">Policy on changelog "
620 #. type: Content of: <chapter><section><section><title>
621 #: best-pkging-practices.dbk:434
622 msgid "Writing useful changelog entries"
625 #. type: Content of: <chapter><section><section><para>
626 #: best-pkging-practices.dbk:436
628 "The changelog entry for a package revision documents changes in that "
629 "revision, and only them. Concentrate on describing significant and "
630 "user-visible changes that were made since the last version."
633 #. type: Content of: <chapter><section><section><para>
634 #: best-pkging-practices.dbk:441
636 "Focus on <emphasis>what</emphasis> was changed — who, how and when are "
637 "usually less important. Having said that, remember to politely attribute "
638 "people who have provided notable help in making the package (e.g., those who "
639 "have sent in patches)."
642 #. type: Content of: <chapter><section><section><para>
643 #: best-pkging-practices.dbk:447
645 "There's no need to elaborate the trivial and obvious changes. You can also "
646 "aggregate several changes in one entry. On the other hand, don't be overly "
647 "terse if you have undertaken a major change. Be especially clear if there "
648 "are changes that affect the behaviour of the program. For further "
649 "explanations, use the <filename>README.Debian</filename> file."
652 #. type: Content of: <chapter><section><section><para>
653 #: best-pkging-practices.dbk:454
655 "Use common English so that the majority of readers can comprehend it. Avoid "
656 "abbreviations, tech-speak and jargon when explaining changes that close "
657 "bugs, especially for bugs filed by users that did not strike you as "
658 "particularly technically savvy. Be polite, don't swear."
661 #. type: Content of: <chapter><section><section><para>
662 #: best-pkging-practices.dbk:460
664 "It is sometimes desirable to prefix changelog entries with the names of the "
665 "files that were changed. However, there's no need to explicitly list each "
666 "and every last one of the changed files, especially if the change was small "
667 "or repetitive. You may use wildcards."
670 #. type: Content of: <chapter><section><section><para>
671 #: best-pkging-practices.dbk:466
673 "When referring to bugs, don't assume anything. Say what the problem was, "
674 "how it was fixed, and append the closes: #nnnnn string. See <xref "
675 "linkend=\"upload-bugfix\"/> for more information."
678 #. type: Content of: <chapter><section><section><title>
679 #: best-pkging-practices.dbk:473
680 msgid "Common misconceptions about changelog entries"
683 #. type: Content of: <chapter><section><section><para>
684 #: best-pkging-practices.dbk:475
686 "The changelog entries should <emphasis role=\"strong\">not</emphasis> "
687 "document generic packaging issues (Hey, if you're looking for foo.conf, it's "
688 "in /etc/blah/.), since administrators and users are supposed to be at least "
689 "remotely acquainted with how such things are generally arranged on Debian "
690 "systems. Do, however, mention if you change the location of a configuration "
694 #. type: Content of: <chapter><section><section><para>
695 #: best-pkging-practices.dbk:483
697 "The only bugs closed with a changelog entry should be those that are "
698 "actually fixed in the same package revision. Closing unrelated bugs in the "
699 "changelog is bad practice. See <xref linkend=\"upload-bugfix\"/>."
702 #. type: Content of: <chapter><section><section><para>
703 #: best-pkging-practices.dbk:488
705 "The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
706 "used for random discussion with bug reporters (I don't see segfaults when "
707 "starting foo with option bar; send in more info), general statements on "
708 "life, the universe and everything (sorry this upload took me so long, but I "
709 "caught the flu), or pleas for help (the bug list on this package is huge, "
710 "please lend me a hand). Such things usually won't be noticed by their "
711 "target audience, but may annoy people who wish to read information about "
712 "actual changes in the package. See <xref linkend=\"bug-answering\"/> for "
713 "more information on how to use the bug tracking system."
716 #. type: Content of: <chapter><section><section><para>
717 #: best-pkging-practices.dbk:499
719 "It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
720 "in the first changelog entry of the proper maintainer upload. As we have "
721 "version tracking now, it is enough to keep the NMUed changelog entries and "
722 "just mention this fact in your own changelog entry."
725 #. type: Content of: <chapter><section><section><title>
726 #: best-pkging-practices.dbk:507
727 msgid "Common errors in changelog entries"
730 #. type: Content of: <chapter><section><section><para>
731 #: best-pkging-practices.dbk:509
733 "The following examples demonstrate some common errors or examples of bad "
734 "style in changelog entries."
737 #. type: Content of: <chapter><section><section><screen>
738 #: best-pkging-practices.dbk:513
740 msgid " * Fixed all outstanding bugs.\n"
743 #. type: Content of: <chapter><section><section><para>
744 #: best-pkging-practices.dbk:516
745 msgid "This doesn't tell readers anything too useful, obviously."
748 #. type: Content of: <chapter><section><section><screen>
749 #: best-pkging-practices.dbk:519
751 msgid " * Applied patch from Jane Random.\n"
754 #. type: Content of: <chapter><section><section><para>
755 #: best-pkging-practices.dbk:522
756 msgid "What was the patch about?"
759 #. type: Content of: <chapter><section><section><screen>
760 #: best-pkging-practices.dbk:525
762 msgid " * Late night install target overhaul.\n"
765 #. type: Content of: <chapter><section><section><para>
766 #: best-pkging-practices.dbk:528
768 "Overhaul which accomplished what? Is the mention of late night supposed to "
769 "remind us that we shouldn't trust that code?"
772 #. type: Content of: <chapter><section><section><screen>
773 #: best-pkging-practices.dbk:532
775 msgid " * Fix vsync FU w/ ancient CRTs.\n"
778 #. type: Content of: <chapter><section><section><para>
779 #: best-pkging-practices.dbk:535
781 "Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
782 "curse word!) was actually about, or how it was fixed."
785 #. type: Content of: <chapter><section><section><screen>
786 #: best-pkging-practices.dbk:539
788 msgid " * This is not a bug, closes: #nnnnnn.\n"
791 #. type: Content of: <chapter><section><section><para>
792 #: best-pkging-practices.dbk:542
794 "First of all, there's absolutely no need to upload the package to convey "
795 "this information; instead, use the bug tracking system. Secondly, there's "
796 "no explanation as to why the report is not a bug."
799 #. type: Content of: <chapter><section><section><screen>
800 #: best-pkging-practices.dbk:547
802 msgid " * Has been fixed for ages, but I forgot to close; closes: #54321.\n"
805 #. type: Content of: <chapter><section><section><para>
806 #: best-pkging-practices.dbk:550
808 "If for some reason you didn't mention the bug number in a previous changelog "
809 "entry, there's no problem, just close the bug normally in the BTS. There's "
810 "no need to touch the changelog file, presuming the description of the fix is "
811 "already in (this applies to the fixes by the upstream authors/maintainers as "
812 "well, you don't have to track bugs that they fixed ages ago in your "
816 #. type: Content of: <chapter><section><section><screen>
817 #: best-pkging-practices.dbk:557
819 msgid " * Closes: #12345, #12346, #15432\n"
822 #. type: Content of: <chapter><section><section><para>
823 #: best-pkging-practices.dbk:560
825 "Where's the description? If you can't think of a descriptive message, start "
826 "by inserting the title of each different bug."
829 #. type: Content of: <chapter><section><section><title>
830 #: best-pkging-practices.dbk:566
831 msgid "Supplementing changelogs with <filename>NEWS.Debian</filename> files"
834 #. type: Content of: <chapter><section><section><para>
835 #: best-pkging-practices.dbk:568
837 "Important news about changes in a package can also be put in "
838 "<filename>NEWS.Debian</filename> files. The news will be displayed by tools "
839 "like <systemitem role=\"package\">apt-listchanges</systemitem>, before all "
840 "the rest of the changelogs. This is the preferred means to let the user "
841 "know about significant changes in a package. It is better than using "
842 "<systemitem role=\"package\">debconf</systemitem> notes since it is less "
843 "annoying and the user can go back and refer to the "
844 "<filename>NEWS.Debian</filename> file after the install. And it's better "
845 "than listing major changes in <filename>README.Debian</filename>, since the "
846 "user can easily miss such notes."
849 #. type: Content of: <chapter><section><section><para>
850 #: best-pkging-practices.dbk:579
852 "The file format is the same as a debian changelog file, but leave off the "
853 "asterisks and describe each news item with a full paragraph when necessary "
854 "rather than the more concise summaries that would go in a changelog. It's a "
855 "good idea to run your file through <literal>dpkg-parsechangelog</literal> to "
856 "check its formatting as it will not be automatically checked during build as "
857 "the changelog is. Here is an example of a real "
858 "<filename>NEWS.Debian</filename> file:"
861 #. type: Content of: <chapter><section><section><screen>
862 #: best-pkging-practices.dbk:588
865 "cron (3.0pl1-74) unstable; urgency=low\n"
867 " The checksecurity script is no longer included with the cron package:\n"
868 " it now has its own package, checksecurity. If you liked the\n"
869 " functionality provided with that script, please install the new\n"
872 " -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 "
876 #. type: Content of: <chapter><section><section><para>
877 #: best-pkging-practices.dbk:598
879 "The <filename>NEWS.Debian</filename> file is installed as "
880 "<filename>/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>. "
881 "It is compressed, and always has that name even in Debian native packages. "
882 "If you use <literal>debhelper</literal>, "
883 "<literal>dh_installchangelogs</literal> will install "
884 "<filename>debian/NEWS</filename> files for you."
887 #. type: Content of: <chapter><section><section><para>
888 #: best-pkging-practices.dbk:605
890 "Unlike changelog files, you need not update <filename>NEWS.Debian</filename> "
891 "files with every release. Only update them if you have something "
892 "particularly newsworthy that user should know about. If you have no news at "
893 "all, there's no need to ship a <filename>NEWS.Debian</filename> file in your "
894 "package. No news is good news!"
897 #. type: Content of: <chapter><section><title>
898 #: best-pkging-practices.dbk:627
899 msgid "Best practices for maintainer scripts"
902 #. type: Content of: <chapter><section><para>
903 #: best-pkging-practices.dbk:629
905 "Maintainer scripts include the files <filename>debian/postinst</filename>, "
906 "<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
907 "<filename>debian/postrm</filename>. These scripts take care of any package "
908 "installation or deinstallation setup which isn't handled merely by the "
909 "creation or removal of files and directories. The following instructions "
910 "supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
913 #. type: Content of: <chapter><section><para>
914 #: best-pkging-practices.dbk:637
916 "Maintainer scripts must be idempotent. That means that you need to make "
917 "sure nothing bad will happen if the script is called twice where it would "
918 "usually be called once."
921 #. type: Content of: <chapter><section><para>
922 #: best-pkging-practices.dbk:642
924 "Standard input and output may be redirected (e.g. into pipes) for logging "
925 "purposes, so don't rely on them being a tty."
928 #. type: Content of: <chapter><section><para>
929 #: best-pkging-practices.dbk:646
931 "All prompting or interactive configuration should be kept to a minimum. "
932 "When it is necessary, you should use the <systemitem "
933 "role=\"package\">debconf</systemitem> package for the interface. Remember "
934 "that prompting in any case can only be in the <literal>configure</literal> "
935 "stage of the <filename>postinst</filename> script."
938 #. type: Content of: <chapter><section><para>
939 #: best-pkging-practices.dbk:653
941 "Keep the maintainer scripts as simple as possible. We suggest you use pure "
942 "POSIX shell scripts. Remember, if you do need any bash features, the "
943 "maintainer script must have a bash shebang line. POSIX shell or Bash are "
944 "preferred to Perl, since they enable <systemitem "
945 "role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
948 #. type: Content of: <chapter><section><para>
949 #: best-pkging-practices.dbk:660
951 "If you change your maintainer scripts, be sure to test package removal, "
952 "double installation, and purging. Be sure that a purged package is "
953 "completely gone, that is, it must remove any files created, directly or "
954 "indirectly, in any maintainer script."
957 #. type: Content of: <chapter><section><para>
958 #: best-pkging-practices.dbk:666
960 "If you need to check for the existence of a command, you should use "
964 #. type: Content of: <chapter><section><programlisting>
965 #: best-pkging-practices.dbk:669
967 msgid "if [ -x /usr/sbin/install-docs ]; then ..."
970 #. type: Content of: <chapter><section><para>
971 #: best-pkging-practices.dbk:671
973 "If you don't wish to hard-code the path of a command in your maintainer "
974 "script, the following POSIX-compliant shell function may help:"
977 #. type: Content of: <chapter><section><para>
978 #: best-pkging-practices.dbk:676
980 "You can use this function to search <varname>$PATH</varname> for a command "
981 "name, passed as an argument. It returns true (zero) if the command was "
982 "found, and false if not. This is really the most portable way, since "
983 "<literal>command -v</literal>, <command>type</command>, and "
984 "<command>which</command> are not POSIX."
987 #. type: Content of: <chapter><section><para>
988 #: best-pkging-practices.dbk:683
990 "While <command>which</command> is an acceptable alternative, since it is "
991 "from the required <systemitem role=\"package\">debianutils</systemitem> "
992 "package, it's not on the root partition. That is, it's in "
993 "<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
994 "can't use it in scripts which are run before the <filename>/usr</filename> "
995 "partition is mounted. Most scripts won't have this problem, though."
998 #. type: Content of: <chapter><section><title>
999 #: best-pkging-practices.dbk:693
1001 "Configuration management with <systemitem "
1002 "role=\"package\">debconf</systemitem>"
1005 #. type: Content of: <chapter><section><para>
1006 #: best-pkging-practices.dbk:695
1008 "<systemitem role=\"package\">Debconf</systemitem> is a configuration "
1009 "management system which can be used by all the various packaging scripts "
1010 "(<filename>postinst</filename> mainly) to request feedback from the user "
1011 "concerning how to configure the package. Direct user interactions must now "
1012 "be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
1013 "interaction. This will enable non-interactive installations in the future."
1016 #. type: Content of: <chapter><section><para>
1017 #: best-pkging-practices.dbk:703
1019 "Debconf is a great tool but it is often poorly used. Many common mistakes "
1020 "are listed in the <citerefentry> "
1021 "<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
1022 "</citerefentry> man page. It is something that you must read if you decide "
1023 "to use debconf. Also, we document some best practices here."
1026 #. type: Content of: <chapter><section><para>
1027 #: best-pkging-practices.dbk:710
1029 "These guidelines include some writing style and typography recommendations, "
1030 "general considerations about debconf usage as well as more specific "
1031 "recommendations for some parts of the distribution (the installation system "
1035 #. type: Content of: <chapter><section><section><title>
1036 #: best-pkging-practices.dbk:716
1037 msgid "Do not abuse debconf"
1040 #. type: Content of: <chapter><section><section><para>
1041 #: best-pkging-practices.dbk:718
1043 "Since debconf appeared in Debian, it has been widely abused and several "
1044 "criticisms received by the Debian distribution come from debconf abuse with "
1045 "the need of answering a wide bunch of questions before getting any little "
1049 #. type: Content of: <chapter><section><section><para>
1050 #: best-pkging-practices.dbk:724
1052 "Keep usage notes to what they belong: the <filename>NEWS.Debian</filename>, "
1053 "or <filename>README.Debian</filename> file. Only use notes for important "
1054 "notes which may directly affect the package usability. Remember that notes "
1055 "will always block the install until confirmed or bother the user by email."
1058 #. type: Content of: <chapter><section><section><para>
1059 #: best-pkging-practices.dbk:730
1061 "Carefully choose the questions priorities in maintainer scripts. See "
1062 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1063 "<manvolnum>7</manvolnum> </citerefentry> for details about priorities. Most "
1064 "questions should use medium and low priorities."
1067 #. type: Content of: <chapter><section><section><title>
1068 #: best-pkging-practices.dbk:738
1069 msgid "General recommendations for authors and translators"
1072 #. type: Content of: <chapter><section><section><section><title>
1073 #: best-pkging-practices.dbk:740
1074 msgid "Write correct English"
1077 #. type: Content of: <chapter><section><section><section><para>
1078 #: best-pkging-practices.dbk:742
1080 "Most Debian package maintainers are not native English speakers. So, "
1081 "writing properly phrased templates may not be easy for them."
1084 #. type: Content of: <chapter><section><section><section><para>
1085 #: best-pkging-practices.dbk:746
1087 "Please use (and abuse) &email-debian-l10n-english; mailing list. Have your "
1088 "templates proofread."
1091 #. type: Content of: <chapter><section><section><section><para>
1092 #: best-pkging-practices.dbk:750
1094 "Badly written templates give a poor image of your package, of your "
1095 "work... or even of Debian itself."
1098 #. type: Content of: <chapter><section><section><section><para>
1099 #: best-pkging-practices.dbk:754
1101 "Avoid technical jargon as much as possible. If some terms sound common to "
1102 "you, they may be impossible to understand for others. If you cannot avoid "
1103 "them, try to explain them (use the extended description). When doing so, "
1104 "try to balance between verbosity and simplicity."
1107 #. type: Content of: <chapter><section><section><section><title>
1108 #: best-pkging-practices.dbk:762
1109 msgid "Be kind to translators"
1112 #. type: Content of: <chapter><section><section><section><para>
1113 #: best-pkging-practices.dbk:764
1115 "Debconf templates may be translated. Debconf, along with its sister package "
1116 "<command>po-debconf</command> offers a simple framework for getting "
1117 "templates translated by translation teams or even individuals."
1120 #. type: Content of: <chapter><section><section><section><para>
1121 #: best-pkging-practices.dbk:769
1123 "Please use gettext-based templates. Install <systemitem "
1124 "role=\"package\">po-debconf</systemitem> on your development system and read "
1125 "its documentation (<command>man po-debconf</command> is a good start)."
1128 #. type: Content of: <chapter><section><section><section><para>
1129 #: best-pkging-practices.dbk:774
1131 "Avoid changing templates too often. Changing templates text induces more "
1132 "work to translators which will get their translation fuzzied. A fuzzy "
1133 "translation is a string for which the original changed since it was "
1134 "translated, therefore requiring some update by a translator to be usable. "
1135 "When changes are small enough, the original translation is kept in PO files "
1136 "but marked as <literal>fuzzy</literal>."
1139 #. type: Content of: <chapter><section><section><section><para>
1140 #: best-pkging-practices.dbk:782
1142 "If you plan to do changes to your original templates, please use the "
1143 "notification system provided with the <systemitem "
1144 "role=\"package\">po-debconf</systemitem> package, namely the "
1145 "<command>podebconf-report-po</command>, to contact translators. Most active "
1146 "translators are very responsive and getting their work included along with "
1147 "your modified templates will save you additional uploads. If you use "
1148 "gettext-based templates, the translator's name and e-mail addresses are "
1149 "mentioned in the PO files headers and will be used by "
1150 "<command>podebconf-report-po</command>."
1153 #. type: Content of: <chapter><section><section><section><para>
1154 #: best-pkging-practices.dbk:794
1155 msgid "A recommended use of that utility is:"
1158 #. type: Content of: <chapter><section><section><section><programlisting>
1159 #: best-pkging-practices.dbk:796
1162 "cd debian/po && podebconf-report-po --call --languageteam "
1163 "--withtranslators --deadline=\"+10 days\""
1166 #. type: Content of: <chapter><section><section><section><para>
1167 #: best-pkging-practices.dbk:798
1169 "This command will first synchronize the PO and POT files in "
1170 "<filename>debian/po</filename> with the templates files listed in "
1171 "<filename>debian/po/POTFILES.in</filename>. Then, it will send a call for "
1172 "new translations, in the &email-debian-i18n; mailing list. Finally, it will "
1173 "also send a call for translation updates to the language team (mentioned in "
1174 "the <literal>Language-Team</literal> field of each PO file) as well as the "
1175 "last translator (mentioned in <literal>Last-translator</literal>)."
1178 #. type: Content of: <chapter><section><section><section><para>
1179 #: best-pkging-practices.dbk:807
1181 "Giving a deadline to translators is always appreciated, so that they can "
1182 "organize their work. Please remember that some translation teams have a "
1183 "formalized translate/review process and a delay lower than 10 days is "
1184 "considered as unreasonable. A shorter delay puts too much pressure on "
1185 "translation teams and should be kept for very minor changes."
1188 #. type: Content of: <chapter><section><section><section><para>
1189 #: best-pkging-practices.dbk:814
1191 "If in doubt, you may also contact the translation team for a given language "
1192 "(debian-l10n-xxxxx@&lists-host;), or the &email-debian-i18n; mailing list."
1195 #. type: Content of: <chapter><section><section><section><title>
1196 #: best-pkging-practices.dbk:821
1197 msgid "Unfuzzy complete translations when correcting typos and spelling"
1200 #. type: Content of: <chapter><section><section><section><para>
1201 #: best-pkging-practices.dbk:823
1203 "When the text of a debconf template is corrected and you are <emphasis "
1204 "role=\"strong\">sure</emphasis> that the change does <emphasis "
1205 "role=\"strong\">not</emphasis> affect translations, please be kind to "
1206 "translators and <emphasis>unfuzzy</emphasis> their translations."
1209 #. type: Content of: <chapter><section><section><section><para>
1210 #: best-pkging-practices.dbk:829
1212 "If you don't do so, the whole template will not be translated as long as a "
1213 "translator will send you an update."
1216 #. type: Content of: <chapter><section><section><section><para>
1217 #: best-pkging-practices.dbk:833
1219 "To <emphasis>unfuzzy</emphasis> translations, you can use two methods. The "
1220 "first method does <emphasis>preventive</emphasis> search and replace actions "
1221 "in the PO files. The latter uses <command>gettext</command> utilities to "
1222 "<emphasis>unfuzzy</emphasis> strings."
1225 #. type: Content of: <chapter><section><section><section><para>
1226 #: best-pkging-practices.dbk:839
1227 msgid "<emphasis>Preventive unfuzzy</emphasis> method:"
1230 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1231 #: best-pkging-practices.dbk:844
1233 "Try finding a complete translation file <emphasis "
1234 "role=\"strong\">before</emphasis> the change:"
1237 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1238 #: best-pkging-practices.dbk:847 best-pkging-practices.dbk:918
1241 "for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics "
1245 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1246 #: best-pkging-practices.dbk:849
1248 "The file only showing <emphasis>translated</emphasis> items will be used as "
1249 "the reference file. If there is none (which should not happen if you take "
1250 "care to properly interact with translators), you should use the file with "
1251 "the most translated strings."
1254 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1255 #: best-pkging-practices.dbk:857
1257 "Identify the needed change. In this example, let's assume the change is "
1258 "about fixing a typo in the word <literal>typo</literal> which was "
1259 "inadvertently written as <literal>tpyo</literal>. Therefore, the change is "
1260 "<command>s/tpyo/typo</command>."
1263 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1264 #: best-pkging-practices.dbk:865
1266 "Check that this change is only applied to the place where you really intend "
1267 "to make it and <emphasis role=\"strong\">not</emphasis> in any other place "
1268 "where the original string is appropriate. This specifically applies to "
1269 "change in punctuation, for instance."
1272 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1273 #: best-pkging-practices.dbk:873
1275 "Modify all PO files by using <command>sed</command>. The use of that command "
1276 "is recommended over any text editor to guarantee that the files encoding "
1277 "will not be broken by the edit action:"
1280 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1281 #: best-pkging-practices.dbk:878
1285 "for i in *.po; do sed -i 's/tpyo/typo/g' $i; done\n"
1288 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1289 #: best-pkging-practices.dbk:884
1290 msgid "Change the debconf template file to fix the typo."
1293 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1294 #: best-pkging-practices.dbk:889
1295 msgid "Run <command>debconf-updatepo</command>."
1298 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1299 #: best-pkging-practices.dbk:894
1301 "Check the <filename>foo.po</filename> reference file. Its statistics should "
1305 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1306 #: best-pkging-practices.dbk:898
1308 msgid "msgfmt -o /dev/null --statistics debian/po/foo.po\n"
1311 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1312 #: best-pkging-practices.dbk:903
1314 "If the file's statistics changed, you did something wrong. Try again or ask "
1315 "for help on the &email-debian-i18n; mailing list."
1318 #. type: Content of: <chapter><section><section><section><para>
1319 #: best-pkging-practices.dbk:909
1320 msgid "Gettext utilities method:"
1323 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1324 #: best-pkging-practices.dbk:914
1326 "Put all incomplete PO files out of the way. You can check the completeness "
1327 "by using (needs the <systemitem role=\"package\">gettext</systemitem> "
1328 "package installed):"
1331 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1332 #: best-pkging-practices.dbk:922
1334 "Move all files which report either fuzzy strings to a temporary place. "
1335 "Files which report no fuzzy strings (only translated and untranslated) will "
1339 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1340 #: best-pkging-practices.dbk:929
1342 "Now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
1343 "for the typos and check again that translation are not impacted (typos, "
1344 "spelling errors, sometimes typographical corrections are usually OK)."
1347 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1348 #: best-pkging-practices.dbk:936
1350 "Run <command>debconf-updatepo</command>. This will fuzzy all strings you "
1351 "modified in translations. You can see this by running the above again."
1354 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1355 #: best-pkging-practices.dbk:942
1356 msgid "Use the following command:"
1359 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1360 #: best-pkging-practices.dbk:944
1362 msgid "for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done"
1365 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1366 #: best-pkging-practices.dbk:948
1368 "Move back to <filename>debian/po</filename> the files which showed fuzzy "
1369 "strings in the first step."
1372 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1373 #: best-pkging-practices.dbk:953
1374 msgid "Run <command>debconf-updatepo</command> again."
1377 #. type: Content of: <chapter><section><section><section><title>
1378 #: best-pkging-practices.dbk:960
1379 msgid "Do not make assumptions about interfaces"
1382 #. type: Content of: <chapter><section><section><section><para>
1383 #: best-pkging-practices.dbk:962
1385 "Templates text should not make reference to widgets belonging to some "
1386 "debconf interfaces. Sentences like <emphasis>If you answer "
1387 "Yes...</emphasis> have no meaning for users of graphical interfaces which "
1388 "use checkboxes for boolean questions."
1391 #. type: Content of: <chapter><section><section><section><para>
1392 #: best-pkging-practices.dbk:967
1394 "String templates should also avoid mentioning the default values in their "
1395 "description. First, because this is redundant with the values seen by the "
1396 "users. Also, because these default values may be different from the "
1397 "maintainer choices (for instance, when the debconf database was preseeded)."
1400 #. type: Content of: <chapter><section><section><section><para>
1401 #: best-pkging-practices.dbk:973
1403 "More generally speaking, try to avoid referring to user actions. Just give "
1407 #. type: Content of: <chapter><section><section><section><title>
1408 #: best-pkging-practices.dbk:979
1409 msgid "Do not use first person"
1412 #. type: Content of: <chapter><section><section><section><para>
1413 #: best-pkging-practices.dbk:981
1415 "You should avoid the use of first person (<emphasis>I will do "
1416 "this...</emphasis> or <emphasis>We recommend...</emphasis>). The computer "
1417 "is not a person and the Debconf templates do not speak for the Debian "
1418 "developers. You should use neutral construction. Those of you who already "
1419 "wrote scientific publications, just write your templates like you would "
1420 "write a scientific paper. However, try using active voice if still "
1421 "possible, like <emphasis>Enable this if ...</emphasis> instead of "
1422 "<emphasis>This can be enabled if...</emphasis>."
1425 #. type: Content of: <chapter><section><section><section><title>
1426 #: best-pkging-practices.dbk:991
1427 msgid "Be gender neutral"
1430 #. type: Content of: <chapter><section><section><section><para>
1431 #: best-pkging-practices.dbk:993
1433 "The world is made of men and women. Please use gender-neutral constructions "
1437 #. type: Content of: <chapter><section><section><title>
1438 #: best-pkging-practices.dbk:1001
1439 msgid "Templates fields definition"
1442 #. type: Content of: <chapter><section><section><para>
1443 #: best-pkging-practices.dbk:1003
1445 "This part gives some information which is mostly taken from the "
1446 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1447 "<manvolnum>7</manvolnum> </citerefentry> manual page."
1450 #. type: Content of: <chapter><section><section><section><title>
1451 #: best-pkging-practices.dbk:1008
1455 #. type: Content of: <chapter><section><section><section><section><title>
1456 #: best-pkging-practices.dbk:1010
1460 #. type: Content of: <chapter><section><section><section><section><para>
1461 #: best-pkging-practices.dbk:1012
1462 msgid "Results in a free-form input field that the user can type any string into."
1465 #. type: Content of: <chapter><section><section><section><section><title>
1466 #: best-pkging-practices.dbk:1017
1470 #. type: Content of: <chapter><section><section><section><section><para>
1471 #: best-pkging-practices.dbk:1019
1473 "Prompts the user for a password. Use this with caution; be aware that the "
1474 "password the user enters will be written to debconf's database. You should "
1475 "probably clean that value out of the database as soon as is possible."
1478 #. type: Content of: <chapter><section><section><section><section><title>
1479 #: best-pkging-practices.dbk:1026
1483 #. type: Content of: <chapter><section><section><section><section><para>
1484 #: best-pkging-practices.dbk:1028
1486 "A true/false choice. Remember: true/false, <emphasis role=\"strong\">not "
1487 "yes/no</emphasis>..."
1490 #. type: Content of: <chapter><section><section><section><section><title>
1491 #: best-pkging-practices.dbk:1034
1495 #. type: Content of: <chapter><section><section><section><section><para>
1496 #: best-pkging-practices.dbk:1036
1498 "A choice between one of a number of values. The choices must be specified "
1499 "in a field named 'Choices'. Separate the possible values with commas and "
1500 "spaces, like this: <literal>Choices: yes, no, maybe</literal>."
1503 #. type: Content of: <chapter><section><section><section><section><para>
1504 #: best-pkging-practices.dbk:1041
1506 "If choices are translatable strings, the 'Choices' field may be marked as "
1507 "translatable by using <literal>__Choices</literal>. The double underscore "
1508 "will split out each choice in a separate string."
1511 #. type: Content of: <chapter><section><section><section><section><para>
1512 #: best-pkging-practices.dbk:1046
1514 "The <command>po-debconf</command> system also offers interesting "
1515 "possibilities to only mark <emphasis role=\"strong\">some</emphasis> choices "
1516 "as translatable. Example:"
1519 #. type: Content of: <chapter><section><section><section><section><programlisting>
1520 #: best-pkging-practices.dbk:1051
1523 "Template: foo/bar\n"
1525 "#flag:translate:3\n"
1526 "__Choices: PAL, SECAM, Other\n"
1527 "_Description: TV standard:\n"
1528 " Please choose the TV standard used in your country.\n"
1531 #. type: Content of: <chapter><section><section><section><section><para>
1532 #: best-pkging-practices.dbk:1059
1534 "In that example, only the 'Other' string is translatable while others are "
1535 "acronyms that should not be translated. The above allows only 'Other' to be "
1536 "included in PO and POT files."
1539 #. type: Content of: <chapter><section><section><section><section><para>
1540 #: best-pkging-practices.dbk:1064
1542 "The debconf templates flag system offers many such possibilities. The "
1543 "<citerefentry> <refentrytitle>po-debconf</refentrytitle> "
1544 "<manvolnum>7</manvolnum> </citerefentry> manual page lists all these "
1548 #. type: Content of: <chapter><section><section><section><section><title>
1549 #: best-pkging-practices.dbk:1072
1553 #. type: Content of: <chapter><section><section><section><section><para>
1554 #: best-pkging-practices.dbk:1074
1556 "Like the select data type, except the user can choose any number of items "
1557 "from the choices list (or chose none of them)."
1560 #. type: Content of: <chapter><section><section><section><section><title>
1561 #: best-pkging-practices.dbk:1080
1565 #. type: Content of: <chapter><section><section><section><section><para>
1566 #: best-pkging-practices.dbk:1082
1568 "Rather than being a question per se, this datatype indicates a note that can "
1569 "be displayed to the user. It should be used only for important notes that "
1570 "the user really should see, since debconf will go to great pains to make "
1571 "sure the user sees it; halting the install for them to press a key, and even "
1572 "mailing the note to them in some cases."
1575 #. type: Content of: <chapter><section><section><section><section><title>
1576 #: best-pkging-practices.dbk:1091
1580 #. type: Content of: <chapter><section><section><section><section><para>
1581 #: best-pkging-practices.dbk:1093
1582 msgid "This type is now considered obsolete: don't use it."
1585 #. type: Content of: <chapter><section><section><section><section><title>
1586 #: best-pkging-practices.dbk:1098
1590 #. type: Content of: <chapter><section><section><section><section><para>
1591 #: best-pkging-practices.dbk:1100
1593 "This type is designed to handle error messages. It is mostly similar to the "
1594 "note type. Frontends may present it differently (for instance, the dialog "
1595 "frontend of cdebconf draws a red screen instead of the usual blue one)."
1598 #. type: Content of: <chapter><section><section><section><section><para>
1599 #: best-pkging-practices.dbk:1105
1601 "It is recommended to use this type for any message that needs user attention "
1602 "for a correction of any kind."
1605 #. type: Content of: <chapter><section><section><section><title>
1606 #: best-pkging-practices.dbk:1113
1607 msgid "Description: short and extended description"
1610 #. type: Content of: <chapter><section><section><section><para>
1611 #: best-pkging-practices.dbk:1115
1613 "Template descriptions have two parts: short and extended. The short "
1614 "description is in the Description: line of the template."
1617 #. type: Content of: <chapter><section><section><section><para>
1618 #: best-pkging-practices.dbk:1119
1620 "The short description should be kept short (50 characters or so) so that it "
1621 "may be accommodated by most debconf interfaces. Keeping it short also helps "
1622 "translators, as usually translations tend to end up being longer than the "
1626 #. type: Content of: <chapter><section><section><section><para>
1627 #: best-pkging-practices.dbk:1125
1629 "The short description should be able to stand on its own. Some interfaces "
1630 "do not show the long description by default, or only if the user explicitely "
1631 "asks for it or even do not show it at all. Avoid things like What do you "
1635 #. type: Content of: <chapter><section><section><section><para>
1636 #: best-pkging-practices.dbk:1131
1638 "The short description does not necessarily have to be a full sentence. This "
1639 "is part of the keep it short and efficient recommendation."
1642 #. type: Content of: <chapter><section><section><section><para>
1643 #: best-pkging-practices.dbk:1135
1645 "The extended description should not repeat the short description word for "
1646 "word. If you can't think up a long description, then first, think some "
1647 "more. Post to debian-devel. Ask for help. Take a writing class! That "
1648 "extended description is important. If after all that you still can't come "
1649 "up with anything, leave it blank."
1652 #. type: Content of: <chapter><section><section><section><para>
1653 #: best-pkging-practices.dbk:1142
1655 "The extended description should use complete sentences. Paragraphs should "
1656 "be kept short for improved readability. Do not mix two ideas in the same "
1657 "paragraph but rather use another paragraph."
1660 #. type: Content of: <chapter><section><section><section><para>
1661 #: best-pkging-practices.dbk:1147
1663 "Don't be too verbose. User tend to ignore too long screens. 20 lines are "
1664 "by experience a border you shouldn't cross, because that means that in the "
1665 "classical dialog interface, people will need to scroll, and lot of people "
1666 "just don't do that."
1669 #. type: Content of: <chapter><section><section><section><para>
1670 #: best-pkging-practices.dbk:1153
1672 "The extended description should <emphasis role=\"strong\">never</emphasis> "
1673 "include a question."
1676 #. type: Content of: <chapter><section><section><section><para>
1677 #: best-pkging-practices.dbk:1157
1679 "For specific rules depending on templates type (string, boolean, etc.), "
1680 "please read below."
1683 #. type: Content of: <chapter><section><section><section><title>
1684 #: best-pkging-practices.dbk:1163
1688 #. type: Content of: <chapter><section><section><section><para>
1689 #: best-pkging-practices.dbk:1165
1691 "This field should be used for select and multiselect types. It contains the "
1692 "possible choices which will be presented to users. These choices should be "
1693 "separated by commas."
1696 #. type: Content of: <chapter><section><section><section><title>
1697 #: best-pkging-practices.dbk:1172
1701 #. type: Content of: <chapter><section><section><section><para>
1702 #: best-pkging-practices.dbk:1174
1704 "This field is optional. It contains the default answer for string, select "
1705 "and multiselect templates. For multiselect templates, it may contain a "
1706 "comma-separated list of choices."
1709 #. type: Content of: <chapter><section><section><title>
1710 #: best-pkging-practices.dbk:1183
1711 msgid "Templates fields specific style guide"
1714 #. type: Content of: <chapter><section><section><section><title>
1715 #: best-pkging-practices.dbk:1185
1719 #. type: Content of: <chapter><section><section><section><para>
1720 #: best-pkging-practices.dbk:1187
1722 "No specific indication except: use the appropriate type by referring to the "
1726 #. type: Content of: <chapter><section><section><section><title>
1727 #: best-pkging-practices.dbk:1193
1728 msgid "Description field"
1731 #. type: Content of: <chapter><section><section><section><para>
1732 #: best-pkging-practices.dbk:1195
1734 "Below are specific instructions for properly writing the Description (short "
1735 "and extended) depending on the template type."
1738 #. type: Content of: <chapter><section><section><section><section><title>
1739 #: best-pkging-practices.dbk:1199
1740 msgid "String/password templates"
1743 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1744 #: best-pkging-practices.dbk:1203
1746 "The short description is a prompt and <emphasis "
1747 "role=\"strong\">not</emphasis> a title. Avoid question style prompts (IP "
1748 "Address?) in favour of opened prompts (IP address:). The use of colons is "
1752 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1753 #: best-pkging-practices.dbk:1210
1755 "The extended description is a complement to the short description. In the "
1756 "extended part, explain what is being asked, rather than ask the same "
1757 "question again using longer words. Use complete sentences. Terse writing "
1758 "style is strongly discouraged."
1761 #. type: Content of: <chapter><section><section><section><section><title>
1762 #: best-pkging-practices.dbk:1220
1763 msgid "Boolean templates"
1766 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1767 #: best-pkging-practices.dbk:1224
1769 "The short description should be phrased in the form of a question which "
1770 "should be kept short and should generally end with a question mark. Terse "
1771 "writing style is permitted and even encouraged if the question is rather "
1772 "long (remember that translations are often longer than original versions)."
1775 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1776 #: best-pkging-practices.dbk:1232
1778 "Again, please avoid referring to specific interface widgets. A common "
1779 "mistake for such templates is if you answer Yes-type constructions."
1782 #. type: Content of: <chapter><section><section><section><section><title>
1783 #: best-pkging-practices.dbk:1240
1784 msgid "Select/Multiselect"
1787 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1788 #: best-pkging-practices.dbk:1244
1790 "The short description is a prompt and <emphasis "
1791 "role=\"strong\">not</emphasis> a title. Do <emphasis "
1792 "role=\"strong\">not</emphasis> use useless Please choose... constructions. "
1793 "Users are clever enough to figure out they have to choose something...:)"
1796 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1797 #: best-pkging-practices.dbk:1252
1799 "The extended description will complete the short description. It may refer "
1800 "to the available choices. It may also mention that the user may choose more "
1801 "than one of the available choices, if the template is a multiselect one "
1802 "(although the interface often makes this clear)."
1805 #. type: Content of: <chapter><section><section><section><section><title>
1806 #: best-pkging-practices.dbk:1262
1810 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1811 #: best-pkging-practices.dbk:1266
1813 "The short description should be considered to be a <emphasis "
1814 "role=\"strong\">title</emphasis>."
1817 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1818 #: best-pkging-practices.dbk:1271
1820 "The extended description is what will be displayed as a more detailed "
1821 "explanation of the note. Phrases, no terse writing style."
1824 #. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1825 #: best-pkging-practices.dbk:1277
1827 "<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
1828 "most common way to abuse debconf. As written in debconf-devel manual page: "
1829 "it's best to use them only for warning about very serious problems. The "
1830 "<filename>NEWS.Debian</filename> or <filename>README.Debian</filename> files "
1831 "are the appropriate location for a lot of notes. If, by reading this, you "
1832 "consider converting your Note type templates to entries in "
1833 "<filename>NEWS.Debian</filename> or <filename>README.Debian</filename>, plus "
1834 "consider keeping existing translations for the future."
1837 #. type: Content of: <chapter><section><section><section><title>
1838 #: best-pkging-practices.dbk:1292
1839 msgid "Choices field"
1842 #. type: Content of: <chapter><section><section><section><para>
1843 #: best-pkging-practices.dbk:1294
1845 "If the Choices are likely to change often, please consider using the "
1846 "__Choices trick. This will split each individual choice into a single "
1847 "string, which will considerably help translators for doing their work."
1850 #. type: Content of: <chapter><section><section><section><title>
1851 #: best-pkging-practices.dbk:1301 best-pkging-practices.dbk:1339
1852 msgid "Default field"
1855 #. type: Content of: <chapter><section><section><section><para>
1856 #: best-pkging-practices.dbk:1303
1858 "If the default value, for a select template, is likely to vary depending on "
1859 "the user language (for instance, if the choice is a language choice), please "
1860 "use the _Default trick."
1863 #. type: Content of: <chapter><section><section><section><para>
1864 #: best-pkging-practices.dbk:1308
1866 "This special field allow translators to put the most appropriate choice "
1867 "according to their own language. It will become the default choice when "
1868 "their language is used while your own mentioned Default Choice will be used "
1869 "when using English."
1872 #. type: Content of: <chapter><section><section><section><para>
1873 #: best-pkging-practices.dbk:1314
1874 msgid "Example, taken from the geneweb package templates:"
1877 #. type: Content of: <chapter><section><section><section><screen>
1878 #: best-pkging-practices.dbk:1317
1881 "Template: geneweb/lang\n"
1883 "__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech "
1884 "(cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), "
1885 "Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian "
1886 "(it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian "
1887 "(ro), Russian (ru), Spanish (es), Swedish (sv)\n"
1888 "# This is the default choice. Translators may put their own language here\n"
1889 "# instead of the default.\n"
1890 "# WARNING : you MUST use the ENGLISH NAME of your language\n"
1891 "# For instance, the french translator will need to put French (fr) here.\n"
1892 "_Default: English[ translators, please see comment in PO files]\n"
1893 "_Description: Geneweb default language:\n"
1896 #. type: Content of: <chapter><section><section><section><para>
1897 #: best-pkging-practices.dbk:1328
1899 "Note the use of brackets which allow internal comments in debconf fields. "
1900 "Also note the use of comments which will show up in files the translators "
1904 #. type: Content of: <chapter><section><section><section><para>
1905 #: best-pkging-practices.dbk:1333
1907 "The comments are needed as the _Default trick is a bit confusing: the "
1908 "translators may put their own choice"
1911 #. type: Content of: <chapter><section><section><section><para>
1912 #: best-pkging-practices.dbk:1341
1914 "Do NOT use empty default field. If you don't want to use default values, do "
1915 "not use Default at all."
1918 #. type: Content of: <chapter><section><section><section><para>
1919 #: best-pkging-practices.dbk:1345
1921 "If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
1922 "see <xref linkend=\"s6.5.2.2\"/>), consider making this field translatable, "
1923 "if you think it may be translated."
1926 #. type: Content of: <chapter><section><section><section><para>
1927 #: best-pkging-practices.dbk:1350
1929 "If the default value may vary depending on language/country (for instance "
1930 "the default value for a language choice), consider using the special "
1931 "_Default type documented in <citerefentry> "
1932 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1936 #. type: Content of: <chapter><section><title>
1937 #: best-pkging-practices.dbk:1362
1938 msgid "Internationalization"
1941 #. type: Content of: <chapter><section><para>
1942 #: best-pkging-practices.dbk:1364
1944 "This section contains global information for developers to make translators' "
1945 "life easier. More information for translators and developers interrested in "
1946 "internationalization are available in the <ulink "
1947 "url=\"&url-i18n-l10n;\">Internationalisation and localisation in "
1948 "Debian</ulink> documentation."
1951 #. type: Content of: <chapter><section><section><title>
1952 #: best-pkging-practices.dbk:1371
1953 msgid "Handling debconf translations"
1956 #. type: Content of: <chapter><section><section><para>
1957 #: best-pkging-practices.dbk:1373
1959 "Like porters, translators have a difficult task. They work on many packages "
1960 "and must collaborate with many different maintainers. Moreover, most of the "
1961 "time, they are not native English speakers, so you may need to be "
1962 "particularly patient with them."
1965 #. type: Content of: <chapter><section><section><para>
1966 #: best-pkging-practices.dbk:1379
1968 "The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
1969 "packages configuration easier for maintainers and for users. Originally, "
1970 "translation of debconf templates was handled with "
1971 "<command>debconf-mergetemplate</command>. However, that technique is now "
1972 "deprecated; the best way to accomplish <systemitem "
1973 "role=\"package\">debconf</systemitem> internationalization is by using the "
1974 "<systemitem role=\"package\">po-debconf</systemitem> package. This method "
1975 "is easier both for maintainer and translators; transition scripts are "
1979 #. type: Content of: <chapter><section><section><para>
1980 #: best-pkging-practices.dbk:1389
1982 "Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
1983 "is stored in <filename>.po</filename> files (drawing from "
1984 "<command>gettext</command> translation techniques). Special template files "
1985 "contain the original messages and mark which fields are translatable. When "
1986 "you change the value of a translatable field, by calling "
1987 "<command>debconf-updatepo</command>, the translation is marked as needing "
1988 "attention from the translators. Then, at build time, the "
1989 "<command>dh_installdebconf</command> program takes care of all the needed "
1990 "magic to add the template along with the up-to-date translations into the "
1991 "binary packages. Refer to the <citerefentry> "
1992 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1993 "</citerefentry> manual page for details."
1996 #. type: Content of: <chapter><section><section><title>
1997 #: best-pkging-practices.dbk:1405
1998 msgid "Internationalized documentation"
2001 #. type: Content of: <chapter><section><section><para>
2002 #: best-pkging-practices.dbk:1407
2004 "Internationalizing documentation is crucial for users, but a lot of labor. "
2005 "There's no way to eliminate all that work, but you can make things easier "
2009 #. type: Content of: <chapter><section><section><para>
2010 #: best-pkging-practices.dbk:1412
2012 "If you maintain documentation of any size, it is easier for translators if "
2013 "they have access to a source control system. That lets translators see the "
2014 "differences between two versions of the documentation, so, for instance, "
2015 "they can see what needs to be retranslated. It is recommended that the "
2016 "translated documentation maintain a note about what source control revision "
2017 "the translation is based on. An interesting system is provided by <ulink "
2018 "url=\"&url-i18n-doc-check;\">doc-check</ulink> in the <systemitem "
2019 "role=\"package\">debian-installer</systemitem> package, which shows an "
2020 "overview of the translation status for any given language, using structured "
2021 "comments for the current revision of the file to be translated and, for a "
2022 "translated file, the revision of the original file the translation is based "
2023 "on. You might wish to adapt and provide that in your VCS area."
2026 #. type: Content of: <chapter><section><section><para>
2027 #: best-pkging-practices.dbk:1426
2029 "If you maintain XML or SGML documentation, we suggest that you isolate any "
2030 "language-independent information and define those as entities in a separate "
2031 "file which is included by all the different translations. This makes it "
2032 "much easier, for instance, to keep URLs up to date across multiple files."
2035 #. type: Content of: <chapter><section><section><para>
2036 #: best-pkging-practices.dbk:1432
2038 "Some tools (e.g. <systemitem role=\"package\">po4a</systemitem>, <systemitem "
2039 "role=\"package\">poxml</systemitem>, or the <systemitem "
2040 "role=\"package\">translate-toolkit</systemitem>) are specialized in "
2041 "extracting the translatable material from different formats. They produce "
2042 "PO files, a format quite common to translators, which permits to see what "
2043 "needs to be retranslated when the translated document is updated."
2046 #. type: Content of: <chapter><section><title>
2047 #: best-pkging-practices.dbk:1444
2048 msgid "Common packaging situations"
2051 #. type: Content of: <chapter><section><section><title>
2052 #: best-pkging-practices.dbk:1455
2053 msgid "Packages using <command>autoconf</command>/<command>automake</command>"
2056 #. type: Content of: <chapter><section><section><para>
2057 #: best-pkging-practices.dbk:1457
2059 "Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
2060 "<filename>config.guess</filename> files up to date is critical for porters, "
2061 "especially on more volatile architectures. Some very good packaging "
2062 "practices for any package using <command>autoconf</command> and/or "
2063 "<command>automake</command> have been synthesized in &file-bpp-autotools; "
2064 "from the <systemitem role=\"package\">autotools-dev</systemitem> package. "
2065 "You're strongly encouraged to read this file and to follow the given "
2069 #. type: Content of: <chapter><section><section><title>
2070 #: best-pkging-practices.dbk:1469
2074 #. type: Content of: <chapter><section><section><para>
2075 #: best-pkging-practices.dbk:1471
2077 "Libraries are always difficult to package for various reasons. The policy "
2078 "imposes many constraints to ease their maintenance and to make sure upgrades "
2079 "are as simple as possible when a new upstream version comes out. Breakage "
2080 "in a library can result in dozens of dependent packages breaking."
2083 #. type: Content of: <chapter><section><section><para>
2084 #: best-pkging-practices.dbk:1477
2086 "Good practices for library packaging have been grouped in <ulink "
2087 "url=\"&url-libpkg-guide;\">the library packaging guide</ulink>."
2090 #. type: Content of: <chapter><section><section><title>
2091 #: best-pkging-practices.dbk:1484
2092 msgid "Documentation"
2095 #. type: Content of: <chapter><section><section><para>
2096 #: best-pkging-practices.dbk:1486
2098 "Be sure to follow the <ulink url=\"&url-debian-policy;ch-docs.html\">Policy "
2099 "on documentation</ulink>."
2102 #. type: Content of: <chapter><section><section><para>
2103 #: best-pkging-practices.dbk:1491
2105 "If your package contains documentation built from XML or SGML, we recommend "
2106 "you not ship the XML or SGML source in the binary package(s). If users want "
2107 "the source of the documentation, they should retrieve the source package."
2110 #. type: Content of: <chapter><section><section><para>
2111 #: best-pkging-practices.dbk:1496
2113 "Policy specifies that documentation should be shipped in HTML format. We "
2114 "also recommend shipping documentation in PDF and plain text format if "
2115 "convenient and if output of reasonable quality is possible. However, it is "
2116 "generally not appropriate to ship plain text versions of documentation whose "
2117 "source format is HTML."
2120 #. type: Content of: <chapter><section><section><para>
2121 #: best-pkging-practices.dbk:1503
2123 "Major shipped manuals should register themselves with <systemitem "
2124 "role=\"package\">doc-base</systemitem> on installation. See the <systemitem "
2125 "role=\"package\">doc-base</systemitem> package documentation for more "
2129 #. type: Content of: <chapter><section><section><para>
2130 #: best-pkging-practices.dbk:1509
2132 "Debian policy (section 12.1) directs that manual pages should accompany "
2133 "every program, utility, and function, and suggests them for other objects "
2134 "like configuration files. If the work you are packaging does not have such "
2135 "manual pages, consider writing them for inclusion in your package, and "
2136 "submitting them upstream."
2139 #. type: Content of: <chapter><section><section><para>
2140 #: best-pkging-practices.dbk:1516
2142 "The manpages do not need to be written directly in the troff format. "
2143 "Popular source formats are Docbook, POD and reST, which can be converted "
2144 "using <command>xsltproc</command>, <command>pod2man</command> and "
2145 "<command>rst2man</command> respectively. To a lesser extent, the "
2146 "<command>help2man</command> program can also be used to write a stub."
2149 #. type: Content of: <chapter><section><section><title>
2150 #: best-pkging-practices.dbk:1525
2151 msgid "Specific types of packages"
2154 #. type: Content of: <chapter><section><section><para>
2155 #: best-pkging-practices.dbk:1527
2157 "Several specific types of packages have special sub-policies and "
2158 "corresponding packaging rules and practices:"
2161 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2162 #: best-pkging-practices.dbk:1533
2164 "Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
2165 "policy</ulink>, some examples of packages following that policy are "
2166 "<systemitem role=\"package\">libdbd-pg-perl</systemitem> (binary perl "
2167 "module) or <systemitem role=\"package\">libmldbm-perl</systemitem> (arch "
2168 "independent perl module)."
2171 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2172 #: best-pkging-practices.dbk:1542
2174 "Python related packages have their python policy; see &file-python-policy; "
2175 "in the <systemitem role=\"package\">python</systemitem> package."
2178 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2179 #: best-pkging-practices.dbk:1549
2181 "Emacs related packages have the <ulink url=\"&url-emacs-policy;\">emacs "
2185 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2186 #: best-pkging-practices.dbk:1556
2188 "Java related packages have their <ulink url=\"&url-java-policy;\">java "
2192 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2193 #: best-pkging-practices.dbk:1563
2195 "Ocaml related packages have their own policy, found in &file-ocaml-policy; "
2196 "from the <systemitem role=\"package\">ocaml</systemitem> package. A good "
2197 "example is the <systemitem role=\"package\">camlzip</systemitem> source "
2201 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2202 #: best-pkging-practices.dbk:1571
2204 "Packages providing XML or SGML DTDs should conform to the recommendations "
2205 "found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
2209 #. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2210 #: best-pkging-practices.dbk:1577
2212 "Lisp packages should register themselves with <systemitem "
2213 "role=\"package\">common-lisp-controller</systemitem>, about which see "
2214 "&file-lisp-controller;."
2217 #. type: Content of: <chapter><section><section><title>
2218 #: best-pkging-practices.dbk:1607
2219 msgid "Architecture-independent data"
2222 #. type: Content of: <chapter><section><section><para>
2223 #: best-pkging-practices.dbk:1609
2225 "It is not uncommon to have a large amount of architecture-independent data "
2226 "packaged with a program. For example, audio files, a collection of icons, "
2227 "wallpaper patterns, or other graphic files. If the size of this data is "
2228 "negligible compared to the size of the rest of the package, it's probably "
2229 "best to keep it all in a single package."
2232 #. type: Content of: <chapter><section><section><para>
2233 #: best-pkging-practices.dbk:1616
2235 "However, if the size of the data is considerable, consider splitting it out "
2236 "into a separate, architecture-independent package "
2237 "(<filename>_all.deb</filename>). By doing this, you avoid needless "
2238 "duplication of the same data into eleven or more .debs, one per each "
2239 "architecture. While this adds some extra overhead into the "
2240 "<filename>Packages</filename> files, it saves a lot of disk space on Debian "
2241 "mirrors. Separating out architecture-independent data also reduces "
2242 "processing time of <command>lintian</command> (see <xref "
2243 "linkend=\"tools-lint\"/>) when run over the entire Debian archive."
2246 #. type: Content of: <chapter><section><section><title>
2247 #: best-pkging-practices.dbk:1628
2248 msgid "Needing a certain locale during build"
2251 #. type: Content of: <chapter><section><section><para>
2252 #: best-pkging-practices.dbk:1630
2254 "If you need a certain locale during build, you can create a temporary file "
2258 #. type: Content of: <chapter><section><section><para>
2259 #: best-pkging-practices.dbk:1634
2261 "If you set <varname>LOCPATH</varname> to the equivalent of "
2262 "<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
2263 "name of the locale you generate, you should get what you want without being "
2264 "root. Something like this:"
2267 #. type: Content of: <chapter><section><section><screen>
2268 #: best-pkging-practices.dbk:1639
2271 "LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
2272 "LOCALE_NAME=en_IN\n"
2273 "LOCALE_CHARSET=UTF-8\n"
2275 "mkdir -p $LOCALE_PATH\n"
2276 "localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
2277 "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
2279 "# Using the locale\n"
2280 "LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date\n"
2283 #. type: Content of: <chapter><section><section><title>
2284 #: best-pkging-practices.dbk:1652
2285 msgid "Make transition packages deborphan compliant"
2288 #. type: Content of: <chapter><section><section><para>
2289 #: best-pkging-practices.dbk:1654
2291 "Deborphan is a program for helping users to detect which packages can safely "
2292 "be removed from the system, i.e. the ones that have no packages depending "
2293 "on them. The default operation is to search only within the libs and "
2294 "oldlibs sections, to hunt down unused libraries. But when passed the right "
2295 "argument, it tries to catch other useless packages."
2298 #. type: Content of: <chapter><section><section><para>
2299 #: best-pkging-practices.dbk:1661
2301 "For example, with <literal>--guess-dummy</literal>, "
2302 "<command>deborphan</command> tries to search all transitional packages which "
2303 "were needed for upgrade but which can now safely be removed. For that, it "
2304 "looks for the string dummy or transitional in their short description."
2307 #. type: Content of: <chapter><section><section><para>
2308 #: best-pkging-practices.dbk:1668
2310 "So, when you are creating such a package, please make sure to add this text "
2311 "to your short description. If you are looking for examples, just run: "
2312 "<command>apt-cache search .|grep dummy</command> or <command>apt-cache "
2313 "search .|grep transitional</command>."
2316 #. type: Content of: <chapter><section><section><para>
2317 #: best-pkging-practices.dbk:1674
2319 "Also, it is recommended to adjust its section to <literal>oldlibs</literal> "
2320 "and its priority to <literal>extra</literal> in order to ease "
2321 "<command>deborphan</command>'s job."
2324 #. type: Content of: <chapter><section><section><title>
2325 #: best-pkging-practices.dbk:1683
2326 msgid "Best practices for <filename>.orig.tar.{gz,bz2,lzma}</filename> files"
2329 #. type: Content of: <chapter><section><section><para>
2330 #: best-pkging-practices.dbk:1685
2332 "There are two kinds of original source tarballs: Pristine source and "
2333 "repackaged upstream source."
2336 #. type: Content of: <chapter><section><section><section><title>
2337 #: best-pkging-practices.dbk:1689
2338 msgid "Pristine source"
2341 #. type: Content of: <chapter><section><section><section><para><footnote><para>
2342 #: best-pkging-practices.dbk:1693
2344 "We cannot prevent upstream authors from changing the tarball they distribute "
2345 "without also incrementing the version number, so there can be no guarantee "
2346 "that a pristine tarball is identical to what upstream "
2347 "<emphasis>currently</emphasis> distributing at any point in time. All that "
2348 "can be expected is that it is identical to something that upstream once "
2349 "<emphasis>did</emphasis> distribute. If a difference arises later (say, if "
2350 "upstream notices that he wasn't using maximal compression in his original "
2351 "distribution and then re-<command>gzip</command>s it), that's just too bad. "
2352 "Since there is no good way to upload a new "
2353 "<filename>.orig.tar.{gz,bz2,lzma}</filename> for the same version, there is "
2354 "not even any point in treating this situation as a bug."
2357 #. type: Content of: <chapter><section><section><section><para>
2358 #: best-pkging-practices.dbk:1691
2360 "The defining characteristic of a pristine source tarball is that the "
2361 "<filename>.orig.tar.{gz,bz2,lzma}</filename> file is byte-for-byte identical "
2362 "to a tarball officially distributed by the upstream author.<placeholder "
2363 "type=\"footnote\" id=\"0\"/> This makes it possible to use checksums to "
2364 "easily verify that all changes between Debian's version and upstream's are "
2365 "contained in the Debian diff. Also, if the original source is huge, "
2366 "upstream authors and others who already have the upstream tarball can save "
2367 "download time if they want to inspect your packaging in detail."
2370 #. type: Content of: <chapter><section><section><section><para>
2371 #: best-pkging-practices.dbk:1711
2373 "There is no universally accepted guidelines that upstream authors follow "
2374 "regarding to the directory structure inside their tarball, but "
2375 "<command>dpkg-source</command> is nevertheless able to deal with most "
2376 "upstream tarballs as pristine source. Its strategy is equivalent to the "
2380 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2381 #: best-pkging-practices.dbk:1719
2382 msgid "It unpacks the tarball in an empty temporary directory by doing"
2385 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
2386 #: best-pkging-practices.dbk:1722
2390 "path/to/<replaceable>packagename</replaceable>_<replaceable>upstream-version</replaceable>.orig.tar.gz "
2394 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2395 #: best-pkging-practices.dbk:1727
2397 "If, after this, the temporary directory contains nothing but one directory "
2398 "and no other files, <command>dpkg-source</command> renames that directory to "
2399 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>. "
2400 "The name of the top-level directory in the tarball does not matter, and is "
2404 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2405 #: best-pkging-practices.dbk:1736
2407 "Otherwise, the upstream tarball must have been packaged without a common "
2408 "top-level directory (shame on the upstream author!). In this case, "
2409 "<command>dpkg-source</command> renames the temporary directory "
2410 "<emphasis>itself</emphasis> to "
2411 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>."
2414 #. type: Content of: <chapter><section><section><section><title>
2415 #: best-pkging-practices.dbk:1747
2416 msgid "Repackaged upstream source"
2419 #. type: Content of: <chapter><section><section><section><para>
2420 #: best-pkging-practices.dbk:1749
2422 "You <emphasis role=\"strong\">should</emphasis> upload packages with a "
2423 "pristine source tarball if possible, but there are various reasons why it "
2424 "might not be possible. This is the case if upstream does not distribute the "
2425 "source as gzipped tar at all, or if upstream's tarball contains "
2426 "non-DFSG-free material that you must remove before uploading."
2429 #. type: Content of: <chapter><section><section><section><para>
2430 #: best-pkging-practices.dbk:1756
2432 "In these cases the developer must construct a suitable "
2433 "<filename>.orig.tar.{gz,bz2,lzma}</filename> file himself. We refer to such "
2434 "a tarball as a repackaged upstream source. Note that a repackaged upstream "
2435 "source is different from a Debian-native package. A repackaged source still "
2436 "comes with Debian-specific changes in a separate "
2437 "<filename>.diff.gz</filename> or "
2438 "<filename>.debian.tar.{gz,bz2,lzma}</filename> and still has a version "
2439 "number composed of <replaceable>upstream-version</replaceable> and "
2440 "<replaceable>debian-version</replaceable>."
2443 #. type: Content of: <chapter><section><section><section><para>
2444 #: best-pkging-practices.dbk:1765
2446 "There may be cases where it is desirable to repackage the source even though "
2447 "upstream distributes a <filename>.tar.{gz,bz2,lzma}</filename> that could in "
2448 "principle be used in its pristine form. The most obvious is if "
2449 "<emphasis>significant</emphasis> space savings can be achieved by "
2450 "recompressing the tar archive or by removing genuinely useless cruft from "
2451 "the upstream archive. Use your own discretion here, but be prepared to "
2452 "defend your decision if you repackage source that could have been pristine."
2455 #. type: Content of: <chapter><section><section><section><para>
2456 #: best-pkging-practices.dbk:1774
2457 msgid "A repackaged <filename>.orig.tar.{gz,bz2,lzma}</filename>"
2460 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2461 #: best-pkging-practices.dbk:1779
2463 "<emphasis role=\"strong\">should</emphasis> be documented in the resulting "
2464 "source package. Detailed information on how the repackaged source was "
2465 "obtained, and on how this can be reproduced should be provided in "
2466 "<filename>debian/copyright</filename>. It is also a good idea to provide a "
2467 "<literal>get-orig-source</literal> target in your "
2468 "<filename>debian/rules</filename> file that repeats the process, as "
2469 "described in the Policy Manual, <ulink "
2470 "url=\"&url-debian-policy;ch-source.html#s-debianrules\">Main building "
2471 "script: <filename>debian/rules</filename></ulink>."
2474 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
2475 #: best-pkging-practices.dbk:1794
2477 "As a special exception, if the omission of non-free files would lead to the "
2478 "source failing to build without assistance from the Debian diff, it might be "
2479 "appropriate to instead edit the files, omitting only the non-free parts of "
2480 "them, and/or explain the situation in a <filename>README.source</filename> "
2481 "file in the root of the source tree. But in that case please also urge the "
2482 "upstream author to make the non-free components easier separable from the "
2483 "rest of the source."
2486 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2487 #: best-pkging-practices.dbk:1792
2489 "<emphasis role=\"strong\">should not</emphasis> contain any file that does "
2490 "not come from the upstream author(s), or whose contents has been changed by "
2491 "you.<placeholder type=\"footnote\" id=\"0\"/>"
2494 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2495 #: best-pkging-practices.dbk:1805
2497 "<emphasis role=\"strong\">should</emphasis>, except where impossible for "
2498 "legal reasons, preserve the entire building and portablility infrastructure "
2499 "provided by the upstream author. For example, it is not a sufficient reason "
2500 "for omitting a file that it is used only when building on MS-DOS. "
2501 "Similarly, a <filename>Makefile</filename> provided by upstream should not "
2502 "be omitted even if the first thing your <filename>debian/rules</filename> "
2503 "does is to overwrite it by running a configure script."
2506 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2507 #: best-pkging-practices.dbk:1814
2509 "(<emphasis>Rationale:</emphasis> It is common for Debian users who need to "
2510 "build software for non-Debian platforms to fetch the source from a Debian "
2511 "mirror rather than trying to locate a canonical upstream distribution "
2515 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2516 #: best-pkging-practices.dbk:1821
2518 "<emphasis role=\"strong\">should</emphasis> use "
2519 "<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>.orig</filename> "
2520 "as the name of the top-level directory in its tarball. This makes it "
2521 "possible to distinguish pristine tarballs from repackaged ones."
2524 #. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2525 #: best-pkging-practices.dbk:1829
2527 "<emphasis role=\"strong\">should</emphasis> be gzipped or bzipped with "
2528 "maximal compression."
2531 #. type: Content of: <chapter><section><section><section><title>
2532 #: best-pkging-practices.dbk:1836
2533 msgid "Changing binary files"
2536 #. type: Content of: <chapter><section><section><section><para>
2537 #: best-pkging-practices.dbk:1838
2539 "Sometimes it is necessary to change binary files contained in the original "
2540 "tarball, or to add binary files that are not in it. This is fully supported "
2541 "when using source packages in “3.0 (quilt)” format, see the "
2542 "<citerefentry><refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum></citerefentry> "
2543 "manual page for details. When using the older format “1.0”, binary files "
2544 "can't be stored in the <filename>.diff.gz</filename> so you must store an "
2545 "<command>uuencode</command>d (or similar) version of the file(s) and decode "
2546 "it at build time in <filename>debian/rules</filename> (and move it in its "
2547 "official location)."
2550 #. type: Content of: <chapter><section><section><title>
2551 #: best-pkging-practices.dbk:1853
2552 msgid "Best practices for debug packages"
2555 #. type: Content of: <chapter><section><section><para>
2556 #: best-pkging-practices.dbk:1855
2558 "A debug package is a package with a name ending in -dbg, that contains "
2559 "additional information that <command>gdb</command> can use. Since Debian "
2560 "binaries are stripped by default, debugging information, including function "
2561 "names and line numbers, is otherwise not available when running "
2562 "<command>gdb</command> on Debian binaries. Debug packages allow users who "
2563 "need this additional debugging information to install it, without bloating a "
2564 "regular system with the information."
2567 #. type: Content of: <chapter><section><section><para>
2568 #: best-pkging-practices.dbk:1863
2570 "It is up to a package's maintainer whether to create a debug package or "
2571 "not. Maintainers are encouraged to create debug packages for library "
2572 "packages, since this can aid in debugging many programs linked to a "
2573 "library. In general, debug packages do not need to be added for all "
2574 "programs; doing so would bloat the archive. But if a maintainer finds that "
2575 "users often need a debugging version of a program, it can be worthwhile to "
2576 "make a debug package for it. Programs that are core infrastructure, such as "
2577 "apache and the X server are also good candidates for debug packages."
2580 #. type: Content of: <chapter><section><section><para>
2581 #: best-pkging-practices.dbk:1873
2583 "Some debug packages may contain an entire special debugging build of a "
2584 "library or other binary, but most of them can save space and build time by "
2585 "instead containing separated debugging symbols that <command>gdb</command> "
2586 "can find and load on the fly when debugging a program or library. The "
2587 "convention in Debian is to keep these symbols in "
2588 "<filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where "
2589 "<replaceable>path</replaceable> is the path to the executable or library. "
2590 "For example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
2591 "<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for "
2592 "<filename>/usr/lib/libfoo.so.1</filename> go in "
2593 "<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>."
2596 #. type: Content of: <chapter><section><section><para>
2597 #: best-pkging-practices.dbk:1885
2599 "The debugging symbols can be extracted from an object file using "
2600 "<command>objcopy --only-keep-debug</command>. Then the object file can be "
2601 "stripped, and <command>objcopy --add-gnu-debuglink</command> used to specify "
2602 "the path to the debugging symbol file. <citerefentry> "
2603 "<refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum> "
2604 "</citerefentry> explains in detail how this works."
2607 #. type: Content of: <chapter><section><section><para>
2608 #: best-pkging-practices.dbk:1893
2610 "The <command>dh_strip</command> command in <systemitem "
2611 "role=\"package\">debhelper</systemitem> supports creating debug packages, "
2612 "and can take care of using <command>objcopy</command> to separate out the "
2613 "debugging symbols for you. If your package uses <systemitem "
2614 "role=\"package\">debhelper</systemitem>, all you need to do is call "
2615 "<command>dh_strip --dbg-package=libfoo-dbg</command>, and add an entry to "
2616 "<filename>debian/control</filename> for the debug package."
2619 #. type: Content of: <chapter><section><section><para>
2620 #: best-pkging-practices.dbk:1900
2622 "Note that the debug package should depend on the package that it provides "
2623 "debugging symbols for, and this dependency should be versioned. For "
2627 #. type: Content of: <chapter><section><section><screen>
2628 #: best-pkging-practices.dbk:1904
2630 msgid "Depends: libfoo (= ${binary:Version})\n"
2633 #. type: Content of: <chapter><section><section><title>
2634 #: best-pkging-practices.dbk:1908
2635 msgid "Best practices for meta-packages"
2638 #. type: Content of: <chapter><section><section><para>
2639 #: best-pkging-practices.dbk:1910
2641 "A meta-package is a mostly empty package that makes it easy to install a "
2642 "coherent set of packages that can evolve over time. It achieves this by "
2643 "depending on all the packages of the set. Thanks to the power of APT, the "
2644 "meta-package maintainer can adjust the dependencies and the user's system "
2645 "will automatically get the supplementary packages. The dropped packages that "
2646 "were automaticaly installed will be also be marked as removal candidates "
2647 "(and are even automatically removed by <command>aptitude</command>). "
2648 "<systemitem role=\"package\">gnome</systemitem> and <systemitem "
2649 "role=\"package\">linux-image-amd64</systemitem> are two examples of "
2650 "meta-packages (built by the source packages <systemitem "
2651 "role=\"package\">meta-gnome2</systemitem> and <systemitem "
2652 "role=\"package\">linux-latest</systemitem>)"
2655 #. type: Content of: <chapter><section><section><para>
2656 #: best-pkging-practices.dbk:1924
2658 "The long description of the meta-package must clearly document its purpose "
2659 "so that the user knows what he will lose if he removes the package. Being "
2660 "explicit about the consequences is recommended. This is particularly "
2661 "important for meta-packages which are installed during initial installation "
2662 "and that have not been explicitly installed by the user. Those tend to be "
2663 "important to ensure smooth system upgrades and the user should be "
2664 "discouraged from uninstalling them to avoid potential breakages."