chiark / gitweb /
Fixed working of the repackaged tarballs section to avoid giving the impression that...
[developers-reference.git] / best-pkging-practices.dbk
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "" [
4   <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
5 ]>
6 <chapter id="best-pkging-practices">
7 <title>Best Packaging Practices</title>
8 <para>
9 Debian's quality is largely due to the <ulink
10 url="&url-debian-policy;">Debian Policy</ulink>, which
11 defines explicit baseline requirements which all Debian packages must fulfill.
12 Yet there is also a shared history of experience which goes beyond the Debian
13 Policy, an accumulation of years of experience in packaging.  Many very
14 talented people have created great tools, tools which help you, the Debian
15 maintainer, create and maintain excellent packages.
16 </para>
17 <para>
18 This chapter provides some best practices for Debian developers.  All
19 recommendations are merely that, and are not requirements or policy.  These are
20 just some subjective hints, advice and pointers collected from Debian
21 developers.  Feel free to pick and choose whatever works best for you.
22 </para>
23 <section id="bpp-debian-rules">
24 <title>Best practices for <filename>debian/rules</filename></title>
25 <para>
26 The following recommendations apply to the <filename>debian/rules</filename>
27 file.  Since <filename>debian/rules</filename> controls the build process and
28 selects the files which go into the package (directly or indirectly), it's
29 usually the file maintainers spend the most time on.
30 </para>
31 <section id="helper-scripts">
32 <title>Helper scripts</title>
33 <para>
34 The rationale for using helper scripts in <filename>debian/rules</filename> is
35 that they let maintainers use and share common logic among many packages.  Take
36 for instance the question of installing menu entries: you need to put the file
37 into <filename>/usr/share/menu</filename> (or <filename>/usr/lib/menu</filename>
38 for executable binary menufiles, if this is needed), and add commands to the
39 maintainer scripts to register and unregister the menu entries.  Since this is
40 a very common thing for packages to do, why should each maintainer rewrite all
41 this on their own, sometimes with bugs?  Also, supposing the menu directory
42 changed, every package would have to be changed.
43 </para>
44 <para>
45 Helper scripts take care of these issues.  Assuming you comply with the
46 conventions expected by the helper script, the helper takes care of all the
47 details.  Changes in policy can be made in the helper script; then packages
48 just need to be rebuilt with the new version of the helper and no other
49 changes.
50 </para>
51 <para>
52 <xref linkend="tools"/> contains a couple of different helpers.  The most
53 common and best (in our opinion) helper system is <systemitem
54 role="package">debhelper</systemitem>.  Previous helper systems, such as
55 <systemitem role="package">debmake</systemitem>, were monolithic: you couldn't
56 pick and choose which part of the helper you found useful, but had to use the
57 helper to do everything.  <systemitem role="package">debhelper</systemitem>,
58 however, is a number of separate little <command>dh_*</command> programs.  For
59 instance, <command>dh_installman</command> installs and compresses man pages,
60 <command>dh_installmenu</command> installs menu files, and so on.  Thus, it
61 offers enough flexibility to be able to use the little helper scripts, where
62 useful, in conjunction with hand-crafted commands in
63 <filename>debian/rules</filename>.
64 </para>
65 <para>
66 You can get started with <systemitem role="package">debhelper</systemitem> by
67 reading <citerefentry> <refentrytitle>debhelper</refentrytitle>
68 <manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that come
69 with the package.  <command>dh_make</command>, from the <systemitem
70 role="package">dh-make</systemitem> package (see <xref linkend="dh-make"/> ),
71 can be used to convert a vanilla source package to a <systemitem
72 role="package">debhelper</systemitem>ized package.  This shortcut, though,
73 should not convince you that you do not need to bother understanding the
74 individual <command>dh_*</command> helpers.  If you are going to use a helper,
75 you do need to take the time to learn to use that helper, to learn its
76 expectations and behavior.
77 </para>
78 <para>
79 Some people feel that vanilla <filename>debian/rules</filename> files are
80 better, since you don't have to learn the intricacies of any helper system.
81 This decision is completely up to you.  Use what works for you.  Many examples
82 of vanilla <filename>debian/rules</filename> files are available at <ulink
83 url="&url-rules-files;"></ulink>.
84 </para>
85 </section>
87 <section id="multiple-patches">
88 <title>Separating your patches into multiple files</title>
89 <para>
90 Big, complex packages may have many bugs that you need to deal with.  If you
91 correct a number of bugs directly in the source, and you're not careful, it can
92 get hard to differentiate the various patches that you applied.  It can get
93 quite messy when you have to update the package to a new upstream version which
94 integrates some of the fixes (but not all).  You can't take the total set of
95 diffs (e.g., from <filename>.diff.gz</filename>) and work out which patch sets
96 to back out as a unit as bugs are fixed upstream.
97 </para>
98 <para>
99 Unfortunately, the packaging system as such currently doesn't provide for
100 separating the patches into several files.  Nevertheless, there are ways to
101 separate patches: the patch files are shipped within the Debian patch file
102 (<filename>.diff.gz</filename>), usually within the
103 <filename>debian/</filename> directory.  The only difference is that they
104 aren't applied immediately by dpkg-source,
105 but by the <literal>build</literal>
106 rule of <filename>debian/rules</filename>,
107 through a dependency on the <literal>patch</literal> rule.
108 Conversely, they are reverted in
109 the <literal>clean</literal> rule,
110 through a dependency on the <literal>unpatch</literal> rule.
111 </para>
112 <para>
113 <command>quilt</command> is the recommended tool for this.
114 It does all of the above, and also allows to manage patch series.
115 See the 
116 <systemitem role="package">quilt</systemitem> package for more information.
117 </para>
118 <para>
119 There are other tools to manage patches, like <command>dpatch</command>,
120 and the patch system integrated with
121 <systemitem role="package">cdbs</systemitem>.
122 </para>
123 </section>
125 <section id="multiple-binary">
126 <title>Multiple binary packages</title>
127 <para>
128 A single source package will often build several binary packages, either to
129 provide several flavors of the same software (e.g., the <systemitem
130 role="package">vim</systemitem> source package) or to make several small
131 packages instead of a big one (e.g., so the user can install only the subset
132 needed, and thus save some disk space).
133 </para>
134 <para>
135 The second case can be easily managed in <filename>debian/rules</filename>.
136 You just need to move the appropriate files from the build directory into the
137 package's temporary trees.  You can do this using <command>install</command> or
138 <command>dh_install</command> from <systemitem
139 role="package">debhelper</systemitem>.  Be sure to check the different
140 permutations of the various packages, ensuring that you have the inter-package
141 dependencies set right in <filename>debian/control</filename>.
142 </para>
143 <para>
144 The first case is a bit more difficult since it involves multiple recompiles of
145 the same software but with different configuration options.  The <systemitem
146 role="package">vim</systemitem> source package is an example of how to manage
147 this using an hand-crafted <filename>debian/rules</filename> file.
148 </para>
149 <!-- FIXME: Find a good debhelper example with multiple configure/make
150      cycles -->
151 </section>
153 </section>
155 <section id="bpp-debian-control">
156 <title>Best practices for <filename>debian/control</filename></title>
157 <para>
158 The following practices are relevant to the <filename>debian/control</filename>
159 file.  They supplement the <ulink
160 url="&url-debian-policy;ch-binary.html#s-descriptions">Policy
161 on package descriptions</ulink>.
162 </para>
163 <para>
164 The description of the package, as defined by the corresponding field in the
165 <filename>control</filename> file, contains both the package synopsis and the
166 long description for the package.  <xref linkend="bpp-desc-basics"/> describes
167 common guidelines for both parts of the package description.  Following that,
168 <xref linkend="bpp-pkg-synopsis"/> provides guidelines specific to the
169 synopsis, and <xref linkend="bpp-pkg-desc"/> contains guidelines specific to
170 the description.
171 </para>
172 <section id="bpp-desc-basics">
173 <title>General guidelines for package descriptions</title>
174 <para>
175 The package description should be written for the average likely user, the
176 average person who will use and benefit from the package.  For instance,
177 development packages are for developers, and can be technical in their
178 language.  More general-purpose applications, such as editors, should be
179 written for a less technical user.
180 </para>
181 <para>
182 Our review of package descriptions lead us to conclude that most package
183 descriptions are technical, that is, are not written to make sense for
184 non-technical users.  Unless your package really is only for technical users,
185 this is a problem.
186 </para>
187 <para>
188 How do you write for non-technical users?  Avoid jargon.  Avoid referring to
189 other applications or frameworks that the user might not be familiar with —
190 GNOME or KDE is fine, since users are probably familiar with these terms, but
191 GTK+ is probably not.  Try not to assume any knowledge at all.  If you must use
192 technical terms, introduce them.
193 </para>
194 <para>
195 Be objective.  Package descriptions are not the place for advocating your
196 package, no matter how much you love it.  Remember that the reader may not care
197 about the same things you care about.
198 </para>
199 <para>
200 References to the names of any other software packages, protocol names,
201 standards, or specifications should use their canonical forms, if one exists.
202 For example, use X Window System, X11, or X; not X Windows, X-Windows, or X
203 Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  Use PostScript, not
204 Postscript or postscript.
205 </para>
206 <para>
207 If you are having problems writing your description, you may wish to send it
208 along to &email-debian-l10n-english; and request feedback.
209 </para>
210 </section>
212 <section id="bpp-pkg-synopsis">
213 <title>The package synopsis, or short description</title>
214 <para>
215 Policy says the synopsis line (the short description) must be concise, not
216 repeating the package name, but also informative.
217 </para>
218 <para>
219 The synopsis functions as a phrase describing the package, not a complete
220 sentence, so sentential punctuation is inappropriate: it does not need extra
221 capital letters or a final period (full stop). It should also omit any initial
222 indefinite or definite article - "a", "an", or "the". Thus for instance:
223 </para>
224 <screen>
225 Package: libeg0
226 Description: exemplification support library
227 </screen>
228 <para>
229 Technically this is a noun phrase minus articles, as opposed to a verb phrase.
230 A good heuristic is that it should be possible to substitute the package name
231 and synopsis into this formula:
232 </para>
233 <para>
234 The package <replaceable>name</replaceable> provides {a,an,the,some}
235 <replaceable>synopsis</replaceable>.
236 </para>
237 <para>
238 Sets of related packages may use an alternative scheme that divides the
239 synopsis into two parts, the first a description of the whole suite and the
240 second a summary of the package's role within it:
241 </para>
242 <screen>
243 Package: eg-tools
244 Description: simple exemplification system (utilities)
246 Package: eg-doc
247 Description: simple exemplification system - documentation
248 </screen>
249 <para>
250 These synopses follow a modified formula. Where a package
251 "<replaceable>name</replaceable>" has a synopsis
252 "<replaceable>suite</replaceable> (<replaceable>role</replaceable>)" or
253 "<replaceable>suite</replaceable> - <replaceable>role</replaceable>", the
254 elements should be phrased so that they fit into the formula:
255 </para>
256 <para>
257 The package <replaceable>name</replaceable> provides {a,an,the}
258 <replaceable>role</replaceable> for the <replaceable>suite</replaceable>.
259 </para>
260 </section>
262 <section id="bpp-pkg-desc">
263 <title>The long description</title>
264 <para>
265 The long description is the primary information available to the user about a
266 package before they install it.  It should provide all the information needed
267 to let the user decide whether to install the package.  Assume that the user
268 has already read the package synopsis.
269 </para>
270 <para>
271 The long description should consist of full and complete sentences.
272 </para>
273 <para>
274 The first paragraph of the long description should answer the following
275 questions: what does the package do?  what task does it help the user
276 accomplish?  It is important to describe this in a non-technical way, unless of
277 course the audience for the package is necessarily technical.
278 </para>
279 <para>
280 The following paragraphs should answer the following questions: Why do I as a
281 user need this package?  What other features does the package have?  What
282 outstanding features and deficiencies are there compared to other packages
283 (e.g., if you need X, use Y instead)?  Is this package related to other
284 packages in some way that is not handled by the package manager (e.g., this is
285 the client for the foo server)?
286 </para>
287 <para>
288 Be careful to avoid spelling and grammar mistakes.  Ensure that you spell-check
289 it.  Both <command>ispell</command> and <command>aspell</command> have special
290 modes for checking <filename>debian/control</filename> files:
291 </para>
292 <screen>
293 ispell -d american -g debian/control
294 </screen>
295 <screen>
296 aspell -d en -D -c debian/control
297 </screen>
298 <para>
299 Users usually expect these questions to be answered in the package description:
300 </para>
301 <itemizedlist>
302 <listitem>
303 <para>
304 What does the package do?  If it is an add-on to another package, then the
305 short description of the package we are an add-on to should be put in here.
306 </para>
307 </listitem>
308 <listitem>
309 <para>
310 Why should I want this package?  This is related to the above, but not the same
311 (this is a mail user agent; this is cool, fast, interfaces with PGP and LDAP
312 and IMAP, has features X, Y, and Z).
313 </para>
314 </listitem>
315 <listitem>
316 <para>
317 If this package should not be installed directly, but is pulled in by another
318 package, this should be mentioned.
319 </para>
320 </listitem>
321 <listitem>
322 <para>
323 If the package is <literal>experimental</literal>, or there are other reasons
324 it should not be used, if there are other packages that should be used instead,
325 it should be here as well.
326 </para>
327 </listitem>
328 <listitem>
329 <para>
330 How is this package different from the competition?  Is it a better
331 implementation?  more features?  different features?  Why should I choose this
332 package.
333 </para>
334 </listitem>
335 <!-- FIXME: what's this?
336 (the second questions is about the class of packages, and
337 this about this particular package, if you have information related to both).
338 -->
339 </itemizedlist>
340 </section>
342 <section id="bpp-upstream-info">
343 <title>Upstream home page</title>
344 <para>
345 We recommend that you add the URL for the package's home page in the
346 <literal>Homepage</literal> field of the <literal>Source</literal> section
347 in <filename>debian/control</filename>.  Adding this information in the
348 package description itself is considered deprecated.
349 </para>
350 </section>
352 <section id="bpp-vcs">
353 <title>Version Control System location</title>
354 <para>
355 There are additional fields for the location of the Version Control System in
356 <filename>debian/control</filename>.
357 </para>
358 <section id="s6.2.5.1">
359 <title>Vcs-Browser</title>
360 <para>
361 Value of this field should be a <literal>http://</literal> URL pointing to a
362 web-browsable copy of the Version Control System repository used to maintain
363 the given package, if available.
364 </para>
365 <para>
366 The information is meant to be useful for the final user, willing to browse the
367 latest work done on the package (e.g.  when looking for the patch fixing a bug
368 tagged as <literal>pending</literal> in the bug tracking system).
369 </para>
370 </section>
372 <section id="s6.2.5.2">
373 <title>Vcs-*</title>
374 <para>
375 Value of this field should be a string identifying unequivocally the location
376 of the Version Control System repository used to maintain the given package, if
377 available.  <literal>*</literal> identify the Version Control System; currently
378 the following systems are supported by the package tracking system:
379 <literal>arch</literal>, <literal>bzr</literal> (Bazaar),
380 <literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>,
381 <literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone),
382 <literal>svn</literal> (Subversion).  It is allowed to specify different VCS
383 fields for the same package: they will all be shown in the PTS web interface.
384 </para>
385 <para>
386 The information is meant to be useful for a user knowledgeable in the given
387 Version Control System and willing to build the current version of a package
388 from the VCS sources.  Other uses of this information might include automatic
389 building of the latest VCS version of the given package.  To this end the
390 location pointed to by the field should better be version agnostic and point to
391 the main branch (for VCSs supporting such a concept).  Also, the location
392 pointed to should be accessible to the final user; fulfilling this requirement
393 might imply pointing to an anonymous access of the repository instead of
394 pointing to an SSH-accessible version of the same.
395 </para>
396 <para>
397 In the following example, an instance of the field for a Subversion repository
398 of the <systemitem role="package">vim</systemitem> package is shown.  Note how
399 the URL is in the <literal>svn://</literal> scheme (instead of
400 <literal>svn+ssh://</literal>) and how it points to the
401 <filename>trunk/</filename> branch.  The use of the
402 <literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields
403 described above is also shown.
404 </para>
405 <screen>
406   Source: vim
407   Section: editors
408   Priority: optional
409   &lt;snip&gt;
410   Vcs-Svn: svn://
411   Vcs-Browser:
412   Homepage:
413 </screen>
414 </section>
416 </section>
418 </section>
420 <section id="bpp-debian-changelog">
421 <title>Best practices for <filename>debian/changelog</filename></title>
422 <para>
423 The following practices supplement the <ulink
424 url="&url-debian-policy;ch-docs.html#s-changelogs">Policy
425 on changelog files</ulink>.
426 </para>
427 <section id="bpp-changelog-do">
428 <title>Writing useful changelog entries</title>
429 <para>
430 The changelog entry for a package revision documents changes in that revision,
431 and only them.  Concentrate on describing significant and user-visible changes
432 that were made since the last version.
433 </para>
434 <para>
435 Focus on <emphasis>what</emphasis> was changed — who, how and when are
436 usually less important.  Having said that, remember to politely attribute
437 people who have provided notable help in making the package (e.g., those who
438 have sent in patches).
439 </para>
440 <para>
441 There's no need to elaborate the trivial and obvious changes.  You can also
442 aggregate several changes in one entry.  On the other hand, don't be overly
443 terse if you have undertaken a major change.  Be especially clear if there are
444 changes that affect the behaviour of the program.  For further explanations,
445 use the <filename>README.Debian</filename> file.
446 </para>
447 <para>
448 Use common English so that the majority of readers can comprehend it.  Avoid
449 abbreviations, tech-speak and jargon when explaining changes that close bugs,
450 especially for bugs filed by users that did not strike you as particularly
451 technically savvy.  Be polite, don't swear.
452 </para>
453 <para>
454 It is sometimes desirable to prefix changelog entries with the names of the
455 files that were changed.  However, there's no need to explicitly list each and
456 every last one of the changed files, especially if the change was small or
457 repetitive.  You may use wildcards.
458 </para>
459 <para>
460 When referring to bugs, don't assume anything.  Say what the problem was, how
461 it was fixed, and append the closes: #nnnnn string.  See <xref
462 linkend="upload-bugfix"/> for more information.
463 </para>
464 </section>
466 <section id="bpp-changelog-misconceptions">
467 <title>Common misconceptions about changelog entries</title>
468 <para>
469 The changelog entries should <emphasis role="strong">not</emphasis> document
470 generic packaging issues (Hey, if you're looking for foo.conf, it's in
471 /etc/blah/.), since administrators and users are supposed to be at least
472 remotely acquainted with how such things are generally arranged on Debian
473 systems.  Do, however, mention if you change the location of a configuration
474 file.
475 </para>
476 <para>
477 The only bugs closed with a changelog entry should be those that are actually
478 fixed in the same package revision.  Closing unrelated bugs in the changelog is
479 bad practice.  See <xref linkend="upload-bugfix"/> .
480 </para>
481 <para>
482 The changelog entries should <emphasis role="strong">not</emphasis> be used for
483 random discussion with bug reporters (I don't see segfaults when starting foo
484 with option bar; send in more info), general statements on life, the universe
485 and everything (sorry this upload took me so long, but I caught the flu), or
486 pleas for help (the bug list on this package is huge, please lend me a hand).
487 Such things usually won't be noticed by their target audience, but may annoy
488 people who wish to read information about actual changes in the package.  See
489 <xref linkend="bug-answering"/> for more information on how to use the bug
490 tracking system.
491 </para>
492 <para>
493 It is an old tradition to acknowledge bugs fixed in non-maintainer uploads in
494 the first changelog entry of the proper maintainer upload.  As we have version
495 tracking now, it is enough to keep the NMUed changelog entries and just mention
496 this fact in your own changelog entry.
497 </para>
498 </section>
500 <section id="bpp-changelog-errors">
501 <title>Common errors in changelog entries</title>
502 <para>
503 The following examples demonstrate some common errors or examples of bad style
504 in changelog entries.
505 </para>
506 <screen>
507   * Fixed all outstanding bugs.
508 </screen>
509 <para>
510 This doesn't tell readers anything too useful, obviously.
511 </para>
512 <screen>
513   * Applied patch from Jane Random.
514 </screen>
515 <para>
516 What was the patch about?
517 </para>
518 <screen>
519   * Late night install target overhaul.
520 </screen>
521 <para>
522 Overhaul which accomplished what?  Is the mention of late night supposed to
523 remind us that we shouldn't trust that code?
524 </para>
525 <screen>
526   * Fix vsync FU w/ ancient CRTs.
527 </screen>
528 <para>
529 Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a
530 curse word!) was actually about, or how it was fixed.
531 </para>
532 <screen>
533   * This is not a bug, closes: #nnnnnn.
534 </screen>
535 <para>
536 First of all, there's absolutely no need to upload the package to convey this
537 information; instead, use the bug tracking system.  Secondly, there's no
538 explanation as to why the report is not a bug.
539 </para>
540 <screen>
541   * Has been fixed for ages, but I forgot to close; closes: #54321.
542 </screen>
543 <para>
544 If for some reason you didn't mention the bug number in a previous changelog
545 entry, there's no problem, just close the bug normally in the BTS.  There's no
546 need to touch the changelog file, presuming the description of the fix is
547 already in (this applies to the fixes by the upstream authors/maintainers as
548 well, you don't have to track bugs that they fixed ages ago in your changelog).
549 </para>
550 <screen>
551   * Closes: #12345, #12346, #15432
552 </screen>
553 <para>
554 Where's the description?  If you can't think of a descriptive message, start by
555 inserting the title of each different bug.
556 </para>
557 </section>
559 <section id="bpp-news-debian">
560 <title>Supplementing changelogs with NEWS.Debian files</title>
561 <para>
562 Important news about changes in a package can also be put in <filename>
563 NEWS.Debian</filename> files.
564 The news will be displayed by tools like apt-listchanges, before all the rest
565 of the changelogs.  This is the preferred means to let the user know about
566 significant changes in a package.  It is better than using debconf notes since
567 it is less annoying and the user can go back and refer to the <filename>
568 NEWS.Debian</filename> file after the install.  And it's better than listing
569 major changes in <filename>README.Debian</filename>, since the user can easily
570 miss such notes.
571 </para>
572 <para>
573 The file format is the same as a debian changelog file, but leave off the
574 asterisks and describe each news item with a full paragraph when necessary
575 rather than the more concise summaries that would go in a changelog.  It's a
576 good idea to run your file through <literal>dpkg-parsechangelog</literal> to
577 check its formatting as it will not be automatically checked during build as
578 the changelog is.  Here is an example of a real <filename>NEWS.Debian
579 </filename> file:
580 </para>
581 <screen>
582 cron (3.0pl1-74) unstable; urgency=low
584     The checksecurity script is no longer included with the cron package:
585     it now has its own package, checksecurity. If you liked the
586     functionality provided with that script, please install the new
587     package.
589  -- Steve Greenland &lt;;  Sat,  6 Sep 2003 17:15:03 -0500
590 </screen>
591 <para>
592 The <filename>NEWS.Debian</filename> file is installed as <filename>
593 /usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>.
594 It is compressed, and always has that name even in Debian native packages.
595 If you use <literal>debhelper</literal>, <literal>dh_installchangelogs
596 </literal> will install <filename>debian/NEWS</filename> files for you.
597 </para>
598 <para>
599 Unlike changelog files, you need not update <filename>NEWS.Debian</filename>
600 files with every release.  Only update them if you have something particularly
601 newsworthy that user should know about.  If you have no news at all, there's no
602 need to ship a <filename>NEWS.Debian</filename> file in your package.  No news
603 is good news!
604 </para>
605 </section>
607 </section>
609 <!--
610 <section id="pkg-mgmt-cvs">
611 <title>Managing a package with CVS</title>
612 <para>
613 FIXME: presentation of cvs-buildpackage, updating sources
614 via CVS (debian/rules refresh).
615 <ulink url="&url-devel-docs;cvs_packages">"&url-devel-docs;cvs_packages"</ulink>
616 </para>
617 </section>
618 -->
620 <section id="bpp-debian-maint-scripts">
621 <title>Best practices for maintainer scripts</title>
622 <para>
623 Maintainer scripts include the files <filename>debian/postinst</filename>,
624 <filename>debian/preinst</filename>, <filename>debian/prerm</filename> and
625 <filename>debian/postrm</filename>.  These scripts take care of any package
626 installation or deinstallation setup which isn't handled merely by the creation
627 or removal of files and directories.  The following instructions supplement the
628 <ulink url="&url-debian-policy;">Debian Policy</ulink>.
629 </para>
630 <para>
631 Maintainer scripts must be idempotent.  That means that you need to make sure
632 nothing bad will happen if the script is called twice where it would usually be
633 called once.
634 </para>
635 <para>
636 Standard input and output may be redirected (e.g.  into pipes) for logging
637 purposes, so don't rely on them being a tty.
638 </para>
639 <para>
640 All prompting or interactive configuration should be kept to a minimum.  When
641 it is necessary, you should use the <systemitem
642 role="package">debconf</systemitem> package for the interface.  Remember that
643 prompting in any case can only be in the <literal>configure</literal> stage of
644 the <filename>postinst</filename> script.
645 </para>
646 <para>
647 Keep the maintainer scripts as simple as possible.  We suggest you use pure
648 POSIX shell scripts.  Remember, if you do need any bash features, the
649 maintainer script must have a bash shebang line.  POSIX shell or Bash are
650 preferred to Perl, since they enable <systemitem
651 role="package">debhelper</systemitem> to easily add bits to the scripts.
652 </para>
653 <para>
654 If you change your maintainer scripts, be sure to test package removal, double
655 installation, and purging.  Be sure that a purged package is completely gone,
656 that is, it must remove any files created, directly or indirectly, in any
657 maintainer script.
658 </para>
659 <para>
660 If you need to check for the existence of a command, you should use something
661 like
662 </para>
663 <programlisting>if [ -x /usr/sbin/install-docs ]; then ...</programlisting>
664 <para>
665 If you don't wish to hard-code the path of a command in your maintainer script,
666 the following POSIX-compliant shell function may help:
667 </para>
668 &example-pathfind;
669 <para>
670 You can use this function to search <literal>$PATH</literal> for a command
671 name, passed as an argument.  It returns true (zero) if the command was found,
672 and false if not.  This is really the most portable way, since <literal>command
673 -v</literal>, <command>type</command>, and <command>which</command> are not
674 POSIX.
675 </para>
676 <para>
677 While <command>which</command> is an acceptable alternative, since it is from
678 the required <systemitem role="package">debianutils</systemitem> package, it's
679 not on the root partition.  That is, it's in <filename>/usr/bin</filename>
680 rather than <filename>/bin</filename>, so one can't use it in scripts which are
681 run before the <filename>/usr</filename> partition is mounted.  Most scripts
682 won't have this problem, though.
683 </para>
684 </section>
686 <section id="bpp-config-mgmt">
687 <title>Configuration management with <systemitem role="package">debconf</systemitem></title>
688 <para>
689 <systemitem role="package">Debconf</systemitem> is a configuration management
690 system which can be used by all the various packaging scripts
691 (<filename>postinst</filename> mainly) to request feedback from the user
692 concerning how to configure the package.  Direct user interactions must now be
693 avoided in favor of <systemitem role="package">debconf</systemitem>
694 interaction.  This will enable non-interactive installations in the future.
695 </para>
696 <para>
697 Debconf is a great tool but it is often poorly used.  Many common mistakes are
698 listed in the <citerefentry> <refentrytitle>debconf-devel</refentrytitle>
699 <manvolnum>7</manvolnum> </citerefentry> man page.  It is something that you
700 must read if you decide to use debconf.  Also, we document some best practices
701 here.
702 </para>
703 <para>
704 These guidelines include some writing style and typography recommendations,
705 general considerations about debconf usage as well as more specific
706 recommendations for some parts of the distribution (the installation system for
707 instance).
708 </para>
709 <section id="s6.5.1">
710 <title>Do not abuse debconf</title>
711 <para>
712 Since debconf appeared in Debian, it has been widely abused and several
713 criticisms received by the Debian distribution come from debconf abuse with the
714 need of answering a wide bunch of questions before getting any little thing
715 installed.
716 </para>
717 <para>
718 Keep usage notes to what they belong: the NEWS.Debian, or README.Debian file.
719 Only use notes for important notes which may directly affect the package
720 usability.  Remember that notes will always block the install until confirmed
721 or bother the user by email.
722 </para>
723 <para>
724 Carefully choose the questions priorities in maintainer scripts.  See
725 <citerefentry> <refentrytitle>debconf-devel</refentrytitle>
726 <manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most
727 questions should use medium and low priorities.
728 </para>
729 </section>
731 <section id="s6.5.2">
732 <title>General recommendations for authors and translators</title>
733 <section id="s6.5.2.1">
734 <title>Write correct English</title>
735 <para>
736 Most Debian package maintainers are not native English speakers.  So, writing
737 properly phrased templates may not be easy for them.
738 </para>
739 <para>
740 Please use (and abuse) &email-debian-l10n-english; mailing
741 list.  Have your templates proofread.
742 </para>
743 <para>
744 Badly written templates give a poor image of your package, of your work...or
745 even of Debian itself.
746 </para>
747 <para>
748 Avoid technical jargon as much as possible.  If some terms sound common to you,
749 they may be impossible to understand for others.  If you cannot avoid them, try
750 to explain them (use the extended description).  When doing so, try to balance
751 between verbosity and simplicity.
752 </para>
753 </section>
755 <section id="s6.5.2.2">
756 <title>Be kind to translators</title>
757 <para>
758 Debconf templates may be translated.  Debconf, along with its sister package
759 <command>po-debconf</command> offers a simple framework for getting templates
760 translated by translation teams or even individuals.
761 </para>
762 <para>
763 Please use gettext-based templates.  Install <systemitem
764 role="package">po-debconf</systemitem> on your development system and read its
765 documentation (<literal>man po-debconf</literal> is a good start).
766 </para>
767 <para>
768 Avoid changing templates too often.  Changing templates text induces more work
769 to translators which will get their translation fuzzied.  A fuzzy translation is
770 a string for which the original changed since it was translated, therefore
771 requiring some update by a translator to be usable.  When changes are small
772 enough, the original translation is kept in PO files but marked as
773 <literal>fuzzy</literal>.
774 </para>
775 <para>
776 If you plan to do changes
777 to your original templates, please use the notification system provided with
778 the <systemitem
779 role="package">po-debconf</systemitem> package, namely the <command>
780 podebconf-report-po</command>, to contact translators.  Most active
781 translators are very responsive and getting their work included along with your
782 modified templates will save you additional uploads.  If you use gettext-based
783 templates, the translator's name and e-mail addresses are mentioned in the PO
784 files headers and will be used by <command>
785 podebconf-report-po</command>.
786 </para>
787 <para>
788 A recommended use of that utility is:
789 </para>
790 <programlisting>cd debian/po &amp;&amp; podebconf-report-po --languageteam --withtranslators --call --deadline="+10 days"</programlisting>
791 <para>
792 This command will first synchronize the PO and POT files in debian/po with
793 the templates files listed in <filename>debian/po/</filename>.
794 Then, it will send a call for translation updates to the language team
795 (mentioned in the <literal>Language-Team</literal> field of each PO file)
796 as well as the last translator (mentioned in
797 <literal>Last-translator</literal>). Finally, it will also send a call for
798 new translations, in the &email-debian-i18n; mailing list.
799 </para>
800 <para>
801 Giving a deadline to translators is always appreciated, so that they can
802 organize their work. Please remember that some translation teams have a
803 formalized translate/review process and a delay lower than 10 days is
804 considered as unreasonable. A shorter delay puts too much pressure on translation
805 teams and should be kept for very minor changes.
806 </para>
807 <para>
808 If in doubt, you may also contact the translation team for a given language
809 (debian-l10n-xxxxx@&lists-host;), or the
810 &email-debian-i18n; mailing list.
811 </para>
812 </section>
814 <section id="s6.5.2.3">
815 <title>Unfuzzy complete translations when correcting typos and spelling</title>
816 <para>
817 When the text of a debconf template is corrected and you are <emphasis
818 role="strong">sure</emphasis> that the change does <emphasis
819 role="strong">not</emphasis> affect translations, please be kind to translators
820 and <emphasis>unfuzzy</emphasis> their translations.
821 </para>
822 <para>
823 If you don't do so, the whole template will not be translated as long as a
824 translator will send you an update.
825 </para>
826 <para>
827 To <emphasis>unfuzzy</emphasis> translations, you can use two methods. The first
828 method does <emphasis>preventive</emphasis> search and replace actions in the
829 PO files. The latter uses <command>gettext</command> utilities to <emphasis>unfuzzy</emphasis>
830 strings.
831 </para>
832 <para>
833 <emphasis>Preventive unfuzzy</emphasis> method:
834 </para>
835 <orderedlist numeration="arabic">
836 <listitem>
837 <para>
838 Try finding a complete translation file <emphasis role="strong"> before</emphasis>
839 the change:
840 </para>
841 <programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
842 --statistics $i; done</programlisting>
843 <para>
844 The file only showing <emphasis>translated</emphasis> items will be used
845 as the reference file. If there is none (which should not happen if you take
846 care to properly interact with translators), you should use the file
847 with the most translated strings.
848 </para>
849 </listitem>
850 <listitem>
851 <para>
852 Identify the needed change. In this example, let's assume the change is about
853 fixing a typo in the word <literal>typo</literal> which was inadvertently
854 written as <literal>tpyo</literal>. Therefore, the change is
855 <command>s/tpyo/typo</command>.
856 </para>
857 </listitem>
858 <listitem>
859 <para>
860 Check that this change is only applied to the place where you really intend
861 to make it and <emphasis role="strong">not</emphasis> in any other place
862 where the original string is appropriate. This specifically applies to
863 change in punctuation, for instance.
864 </para>
865 </listitem>
866 <listitem>
867 <para>
868 Modify all PO files by using <command>sed</command>. The use of that command
869 is recommended over any text editor to guarantee that the files encoding will
870 not be broken by the edit action.
871 </para>
872 <programlisting>
873 cd debian/po
874 for i in *.po; do sed -i 's/tpyo/typo/g' $i; done
875 </programlisting>
876 </listitem>
877 <listitem>
878 <para>
879 Change the debconf template file to fix the typo.
880 </para>
881 </listitem>
882 <listitem>
883 <para>
884 Run <command>debconf-updatepo</command>
885 </para>
886 </listitem>
887 <listitem>
888 <para>
889 Check the <filename>foo.po</filename> reference file. Its statistics should
890 not be changed:
891 </para>
892 <programlisting>
893 msgfmt -o /dev/null --statistics debian/po/foo.po
894 </programlisting>
895 </listitem>
896 <listitem>
897 If the file's statistics changed, you did something wrong. Try again
898 or ask for help on the &email-debian-i18n; mailing list.
899 </listitem>
900 </orderedlist>
901 <para>
902 Gettext utilities method:
903 </para>
904 <orderedlist numeration="arabic">
905 <listitem>
906 <para>
907 Put all incomplete PO files out of the way.  You can check the completeness by
908 using (needs the <systemitem role="package">gettext</systemitem> package
909 installed):
910 </para>
911 <programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
912 --statistics $i; done</programlisting>
913 </listitem>
914 <listitem>
915 <para>
916 move all files which report either fuzzy strings to a temporary place.  Files
917 which report no fuzzy strings (only translated and untranslated) will be kept
918 in place.
919 </para>
920 </listitem>
921 <listitem>
922 <para>
923 now <emphasis role="strong">and now only</emphasis>, modify the template for
924 the typos and check again that translation are not impacted (typos, spelling
925 errors, sometimes typographical corrections are usually OK)
926 </para>
927 </listitem>
928 <listitem>
929 <para>
930 run <command>debconf-updatepo</command>.  This will fuzzy all strings you
931 modified in translations.  You can see this by running the above again
932 </para>
933 </listitem>
934 <listitem>
935 <para>
936 use the following command:
937 </para>
938 <programlisting>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</programlisting>
939 </listitem>
940 <listitem>
941 <para>
942 move back to debian/po the files which showed fuzzy strings in the first step
943 </para>
944 </listitem>
945 <listitem>
946 <para>
947 run <command>debconf-updatepo</command> again
948 </para>
949 </listitem>
950 </orderedlist>
951 </section>
953 <section id="s6.5.2.4">
954 <title>Do not make assumptions about interfaces</title>
955 <para>
956 Templates text should not make reference to widgets belonging to some debconf
957 interfaces.  Sentences like <emphasis>If you answer Yes...</emphasis> have no meaning for users of
958 graphical interfaces which use checkboxes for boolean questions.
959 </para>
960 <para>
961 String templates should also avoid mentioning the default values in their
962 description.  First, because this is redundant with the values seen by the
963 users.  Also, because these default values may be different from the maintainer
964 choices (for instance, when the debconf database was preseeded).
965 </para>
966 <para>
967 More generally speaking, try to avoid referring to user actions.  Just give
968 facts.
969 </para>
970 </section>
972 <section id="s6.5.2.5">
973 <title>Do not use first person</title>
974 <para>
975 You should avoid the use of first person (<emphasis>I will do this...</emphasis> or <emphasis>We
976 recommend...</emphasis>).  The computer is not a person and the Debconf templates do not
977 speak for the Debian developers.  You should use neutral construction.  Those
978 of you who already wrote scientific publications, just write your templates
979 like you would write a scientific paper.  However, try using active voice if
980 still possible, like <emphasis>Enable this if ...</emphasis> instead of <emphasis>This can be enabled if...</emphasis>.
981 </para>
982 </section>
984 <section id="s6.5.2.6">
985 <title>Be gender neutral</title>
986 <para>
987 The world is made of men and women.  Please use gender-neutral constructions in
988 your writing.
989 </para>
990 </section>
992 </section>
994 <section id="s6.5.3">
995 <title>Templates fields definition</title>
996 <para>
997 This part gives some information which is mostly taken from the <citerefentry>
998 <refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum>
999 </citerefentry> manual page.
1000 </para>
1001 <section id="s6.5.3.1">
1002 <title>Type</title>
1003 <section id="s6.">
1004 <title>string:</title>
1005 <para>
1006 Results in a free-form input field that the user can type any string into.
1007 </para>
1008 </section>
1010 <section id="s6.">
1011 <title>password:</title>
1012 <para>
1013 Prompts the user for a password.  Use this with caution; be aware that the
1014 password the user enters will be written to debconf's database.  You should
1015 probably clean that value out of the database as soon as is possible.
1016 </para>
1017 </section>
1019 <section id="s6.">
1020 <title>boolean:</title>
1021 <para>
1022 A true/false choice.  Remember: true/false, <emphasis role="strong">not
1023 yes/no</emphasis>...
1024 </para>
1025 </section>
1027 <section id="s6.">
1028 <title>select:</title>
1029 <para>
1030 A choice between one of a number of values.  The choices must be specified in a
1031 field named 'Choices'.  Separate the possible values with commas and spaces,
1032 like this: <literal>Choices: yes, no, maybe</literal>.
1033 </para>
1034 <para>
1035 If choices are translatable strings, the 'Choices' field may be marked as
1036 translatable by using <literal>__Choices</literal>. The double underscore will split out
1037 each choice in a separate string.
1038 </para>
1039 <para>
1040 The <command>po-debconf</command> system also offers interesting possibilities
1041 to only mark <emphasis role="strong">some</emphasis> choices as translatable.
1042 Example:
1043 </para>
1044 <programlisting>
1045 Template: foo/bar
1046 Type: Select
1047 #flag:translate:3
1048 __Choices: PAL, SECAM, Other
1049 _Description: TV standard:
1050  Please choose the TV standard used in your country.
1051 </programlisting>
1052 <para>
1053 In that example, only the 'Other' string is translatable while others
1054 are acronyms that should not be translated. The above allows only
1055 'Other' to be included in PO and POT files.
1056 </para>
1057 <para>
1058 The debconf templates flag system offers many such possibilities. The
1059 <citerefentry>
1060 <refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
1061 </citerefentry> manual page lists all these possibilities.
1062 </para>
1063 </section>
1065 <section id="s6.">
1066 <title>multiselect:</title>
1067 <para>
1068 Like the select data type, except the user can choose any number of items from
1069 the choices list (or chose none of them).
1070 </para>
1071 </section>
1073 <section id="s6.">
1074 <title>note:</title>
1075 <para>
1076 Rather than being a question per se, this datatype indicates a note that can be
1077 displayed to the user.  It should be used only for important notes that the
1078 user really should see, since debconf will go to great pains to make sure the
1079 user sees it; halting the install for them to press a key, and even mailing the
1080 note to them in some cases.
1081 </para>
1082 </section>
1084 <section id="s6.">
1085 <title>text:</title>
1086 <para>
1087 This type is now considered obsolete: don't use it.
1088 </para>
1089 </section>
1091 <section id="s6.">
1092 <title>error:</title>
1093 <para>
1094 This type is designed to handle error messages.  It is mostly similar to the
1095 note type.  Frontends may present it differently (for instance, the dialog
1096 frontend of cdebconf draws a red screen instead of the usual blue one).
1097 </para>
1098 <para>
1099 It is recommended to use this type for any message that needs user attention
1100 for a correction of any kind.
1101 </para>
1102 </section>
1104 </section>
1106 <section id="s6.5.3.2">
1107 <title>Description: short and extended description</title>
1108 <para>
1109 Template descriptions have two parts: short and extended.  The short
1110 description is in the Description: line of the template.
1111 </para>
1112 <para>
1113 The short description should be kept short (50 characters or so) so that it may
1114 be accomodated by most debconf interfaces.  Keeping it short also helps
1115 translators, as usually translations tend to end up being longer than the
1116 original.
1117 </para>
1118 <para>
1119 The short description should be able to stand on its own.  Some interfaces do
1120 not show the long description by default, or only if the user explicitely asks
1121 for it or even do not show it at all.  Avoid things like What do you want to
1122 do?
1123 </para>
1124 <para>
1125 The short description does not necessarily have to be a full sentence.  This is
1126 part of the keep it short and efficient recommendation.
1127 </para>
1128 <para>
1129 The extended description should not repeat the short description word for word.
1130 If you can't think up a long description, then first, think some more.  Post to
1131 debian-devel.  Ask for help.  Take a writing class!  That extended description
1132 is important.  If after all that you still can't come up with anything, leave
1133 it blank.
1134 </para>
1135 <para>
1136 The extended description should use complete sentences.  Paragraphs should be
1137 kept short for improved readability.  Do not mix two ideas in the same
1138 paragraph but rather use another paragraph.
1139 </para>
1140 <para>
1141 Don't be too verbose.  User tend to ignore too long screens.  20 lines are by
1142 experience a border you shouldn't cross, because that means that in the
1143 classical dialog interface, people will need to scroll, and lot of people just
1144 don't do that.
1145 </para>
1146 <para>
1147 The extended description should <emphasis role="strong">never</emphasis>
1148 include a question.
1149 </para>
1150 <para>
1151 For specific rules depending on templates type (string, boolean, etc.), please
1152 read below.
1153 </para>
1154 </section>
1156 <section id="s6.5.3.3">
1157 <title>Choices</title>
1158 <para>
1159 This field should be used for Select and Multiselect types.  It contains the
1160 possible choices which will be presented to users.  These choices should be
1161 separated by commas.
1162 </para>
1163 </section>
1165 <section id="s6.5.3.4">
1166 <title>Default</title>
1167 <para>
1168 This field is optional.  It contains the default answer for string, select and
1169 multiselect templates.  For multiselect templates, it may contain a
1170 comma-separated list of choices.
1171 </para>
1172 </section>
1174 </section>
1176 <section id="s6.5.4">
1177 <title>Templates fields specific style guide</title>
1178 <section id="s6.5.4.1">
1179 <title>Type field</title>
1180 <para>
1181 No specific indication except: use the appropriate type by referring to the
1182 previous section.
1183 </para>
1184 </section>
1186 <section id="s6.5.4.2">
1187 <title>Description field</title>
1188 <para>
1189 Below are specific instructions for properly writing the Description (short and
1190 extended) depending on the template type.
1191 </para>
1192 <section id="s6.">
1193 <title>String/password templates</title>
1194 <itemizedlist>
1195 <listitem>
1196 <para>
1197 The short description is a prompt and <emphasis role="strong">not</emphasis> a
1198 title.  Avoid question style prompts (IP Address?) in favour of opened prompts
1199 (IP address:).  The use of colons is recommended.
1200 </para>
1201 </listitem>
1202 <listitem>
1203 <para>
1204 The extended description is a complement to the short description.  In the
1205 extended part, explain what is being asked, rather than ask the same question
1206 again using longer words.  Use complete sentences.  Terse writing style is
1207 strongly discouraged.
1208 </para>
1209 </listitem>
1210 </itemizedlist>
1211 </section>
1213 <section id="s6.">
1214 <title>Boolean templates</title>
1215 <itemizedlist>
1216 <listitem>
1217 <para>
1218 The short description should be phrased in the form of a question which should
1219 be kept short and should generally end with a question mark.  Terse writing
1220 style is permitted and even encouraged if the question is rather long (remember
1221 that translations are often longer than original versions)
1222 </para>
1223 </listitem>
1224 <listitem>
1225 <para>
1226 Again, please avoid referring to specific interface widgets.  A common mistake
1227 for such templates is if you answer Yes-type constructions.
1228 </para>
1229 </listitem>
1230 </itemizedlist>
1231 </section>
1233 <section id="s6.">
1234 <title>Select/Multiselect</title>
1235 <itemizedlist>
1236 <listitem>
1237 <para>
1238 The short description is a prompt and <emphasis role="strong">not</emphasis> a
1239 title.  Do <emphasis role="strong">not</emphasis> use useless Please choose...
1240 constructions.  Users are clever enough to figure out they have to choose
1241 something...:)
1242 </para>
1243 </listitem>
1244 <listitem>
1245 <para>
1246 The extended description will complete the short description.  It may refer to
1247 the available choices.  It may also mention that the user may choose more than
1248 one of the available choices, if the template is a multiselect one (although
1249 the interface often makes this clear).
1250 </para>
1251 </listitem>
1252 </itemizedlist>
1253 </section>
1255 <section id="s6.">
1256 <title>Notes</title>
1257 <itemizedlist>
1258 <listitem>
1259 <para>
1260 The short description should be considered to be a *title*.
1261 </para>
1262 </listitem>
1263 <listitem>
1264 <para>
1265 The extended description is what will be displayed as a more detailed
1266 explanation of the note.  Phrases, no terse writing style.
1267 </para>
1268 </listitem>
1269 <listitem>
1270 <para>
1271 <emphasis role="strong">Do not abuse debconf.</emphasis> Notes are the most
1272 common way to abuse debconf.  As written in debconf-devel manual page: it's
1273 best to use them only for warning about very serious problems.  The NEWS.Debian
1274 or README.Debian files are the appropriate location for a lot of notes.  If, by
1275 reading this, you consider converting your Note type templates to entries in
1276 NEWS/Debian or README.Debian, plus consider keeping existing translations for
1277 the future.
1278 </para>
1279 </listitem>
1280 </itemizedlist>
1281 </section>
1283 </section>
1285 <section id="s6.5.4.3">
1286 <title>Choices field</title>
1287 <para>
1288 If the Choices are likely to change often, please consider using the __Choices
1289 trick.  This will split each individual choice into a single string, which will
1290 considerably help translators for doing their work.
1291 </para>
1292 </section>
1294 <section id="s6.5.4.4">
1295 <title>Default field</title>
1296 <para>
1297 If the default value, for a select template, is likely to vary depending on the
1298 user language (for instance, if the choice is a language choice), please use
1299 the _DefaultChoice trick.
1300 </para>
1301 <para>
1302 This special field allow translators to put the most appropriate choice
1303 according to their own language.  It will become the default choice when their
1304 language is used while your own mentioned Default Choice will be used when
1305 using English.
1306 </para>
1307 <para>
1308 Example, taken from the geneweb package templates:
1309 </para>
1310 <screen>
1311 Template: geneweb/lang
1312 Type: select
1313 __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
1314 # This is the default choice. Translators may put their own language here
1315 # instead of the default.
1316 # WARNING : you MUST use the ENGLISH FORM of your language
1317 # For instance, the french translator will need to put French (fr) here.
1318 _DefaultChoice: English (en)[ translators, please see comment in PO files]
1319 _Description: Geneweb default language:
1320 </screen>
1321 <para>
1322 Note the use of brackets which allow internal comments in debconf fields.  Also
1323 note the use of comments which will show up in files the translators will work
1324 with.
1325 </para>
1326 <para>
1327 The comments are needed as the DefaultChoice trick is a bit confusing: the
1328 translators may put their own choice
1329 </para>
1330 </section>
1332 <section id="s6.5.4.5">
1333 <title>Default field</title>
1334 <para>
1335 Do NOT use empty default field.  If you don't want to use default values, do
1336 not use Default at all.
1337 </para>
1338 <para>
1339 If you use po-debconf (and you <emphasis role="strong">should</emphasis>, see
1340 2.2), consider making this field translatable, if you think it may be
1341 translated.
1342 </para>
1343 <para>
1344 If the default value may vary depending on language/country (for instance the
1345 default value for a language choice), consider using the special _DefaultChoice
1346 type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
1347 <manvolnum>7</manvolnum> </citerefentry>).
1348 </para>
1349 </section>
1351 </section>
1353 </section>
1355 <section id="bpp-i18n">
1356 <title>Internationalization</title>
1357 <section id="bpp-i18n-debconf">
1358 <title>Handling debconf translations</title>
1359 <para>
1360 Like porters, translators have a difficult task.  They work on many packages
1361 and must collaborate with many different maintainers.  Moreover, most of the
1362 time, they are not native English speakers, so you may need to be particularly
1363 patient with them.
1364 </para>
1365 <para>
1366 The goal of <systemitem role="package">debconf</systemitem> was to make
1367 packages configuration easier for maintainers and for users.  Originally,
1368 translation of debconf templates was handled with
1369 <command>debconf-mergetemplate</command>.  However, that technique is now
1370 deprecated; the best way to accomplish <systemitem
1371 role="package">debconf</systemitem> internationalization is by using the
1372 <systemitem role="package">po-debconf</systemitem> package.  This method is
1373 easier both for maintainer and translators; transition scripts are provided.
1374 </para>
1375 <para>
1376 Using <systemitem role="package">po-debconf</systemitem>, the translation is
1377 stored in <filename>po</filename> files (drawing from
1378 <command>gettext</command> translation techniques).  Special template files
1379 contain the original messages and mark which fields are translatable.  When you
1380 change the value of a translatable field, by calling
1381 <command>debconf-updatepo</command>, the translation is marked as needing
1382 attention from the translators.  Then, at build time, the
1383 <command>dh_installdebconf</command> program takes care of all the needed magic
1384 to add the template along with the up-to-date translations into the binary
1385 packages.  Refer to the <citerefentry>
1386 <refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
1387 </citerefentry> manual page for details.
1388 </para>
1389 </section>
1391 <section id="bpp-i18n-docs">
1392 <title>Internationalized documentation</title>
1393 <para>
1394 Internationalizing documentation is crucial for users, but a lot of labor.
1395 There's no way to eliminate all that work, but you can make things easier for
1396 translators.
1397 </para>
1398 <para>
1399 If you maintain documentation of any size, its easier for translators if they
1400 have access to a source control system.  That lets translators see the
1401 differences between two versions of the documentation, so, for instance, they
1402 can see what needs to be retranslated.  It is recommended that the translated
1403 documentation maintain a note about what source control revision the
1404 translation is based on.  An interesting system is provided by <ulink
1405 url="&url-i18n-doc-check;">doc-check</ulink> in the
1406 <systemitem role="package">boot-floppies</systemitem> package, which shows an
1407 overview of the translation status for any given language, using structured
1408 comments for the current revision of the file to be translated and, for a
1409 translated file, the revision of the original file the translation is based on.
1410 You might wish to adapt and provide that in your CVS area.
1411 </para>
1412 <para>
1413 If you maintain XML or SGML documentation, we suggest that you isolate any
1414 language-independent information and define those as entities in a separate
1415 file which is included by all the different translations.  This makes it much
1416 easier, for instance, to keep URLs up to date across multiple files.
1417 </para>
1418 </section>
1420 </section>
1422 <section id="bpp-common-situations">
1423 <title>Common packaging situations</title>
1424 <!--
1425 <section id="bpp-kernel">
1426 <title>Kernel modules/patches</title>
1427 <para>
1428 FIXME: Heavy use of kernel-package. provide files in
1429 /etc/modutils/ for module configuration.
1430 </para>
1431 </section>
1432 -->
1433 <section id="bpp-autotools">
1434 <title>Packages using <command>autoconf</command>/<command>automake</command></title>
1435 <para>
1436 Keeping <command>autoconf</command>'s <filename>config.sub</filename> and
1437 <filename>config.guess</filename> files up to date is critical for porters,
1438 especially on more volatile architectures.  Some very good packaging practices
1439 for any package using <command>autoconf</command> and/or
1440 <command>automake</command> have been synthesized in
1441 &file-bpp-autotools; from the
1442 <systemitem role="package">autotools-dev</systemitem> package.  You're strongly
1443 encouraged to read this file and to follow the given recommendations.
1444 </para>
1445 </section>
1447 <section id="bpp-libraries">
1448 <title>Libraries</title>
1449 <para>
1450 Libraries are always difficult to package for various reasons.  The policy
1451 imposes many constraints to ease their maintenance and to make sure upgrades
1452 are as simple as possible when a new upstream version comes out.  Breakage in a
1453 library can result in dozens of dependent packages breaking.
1454 </para>
1455 <para>
1456 Good practices for library packaging have been grouped in <ulink
1457 url="&url-libpkg-guide;">the library
1458 packaging guide</ulink>.
1459 </para>
1460 </section>
1462 <section id="bpp-docs">
1463 <title>Documentation</title>
1464 <para>
1465 Be sure to follow the <ulink
1466 url="&url-debian-policy;ch-docs.html">Policy on
1467 documentation</ulink>.
1468 </para>
1469 <para>
1470 If your package contains documentation built from XML or SGML, we recommend you
1471 not ship the XML or SGML source in the binary package(s).  If users want the
1472 source of the documentation, they should retrieve the source package.
1473 </para>
1474 <para>
1475 Policy specifies that documentation should be shipped in HTML format.  We also
1476 recommend shipping documentation in PDF and plain text format if convenient and
1477 if output of reasonable quality is possible.  However, it is generally not
1478 appropriate to ship plain text versions of documentation whose source format is
1479 HTML.
1480 </para>
1481 <para>
1482 Major shipped manuals should register themselves with <systemitem
1483 role="package">doc-base</systemitem> on installation.  See the <systemitem
1484 role="package">doc-base</systemitem> package documentation for more
1485 information.
1486 </para>
1487 </section>
1489 <section id="bpp-other">
1490 <title>Specific types of packages</title>
1491 <para>
1492 Several specific types of packages have special sub-policies and corresponding
1493 packaging rules and practices:
1494 </para>
1495 <itemizedlist>
1496 <listitem>
1497 <para>
1498 Perl related packages have a <ulink
1499 url="&url-perl-policy;">Perl
1500 policy</ulink>, some examples of packages following that policy are <systemitem
1501 role="package">libdbd-pg-perl</systemitem> (binary perl module) or <systemitem
1502 role="package">libmldbm-perl</systemitem> (arch independent perl module).
1503 </para>
1504 </listitem>
1505 <listitem>
1506 <para>
1507 Python related packages have their python policy; see
1508 &file-python-policy; in the <systemitem
1509 role="package">python</systemitem> package.
1510 </para>
1511 </listitem>
1512 <listitem>
1513 <para>
1514 Emacs related packages have the <ulink
1515 url="&url-emacs-policy;">emacs
1516 policy</ulink>.
1517 </para>
1518 </listitem>
1519 <listitem>
1520 <para>
1521 Java related packages have their <ulink
1522 url="&url-java-policy;">java
1523 policy</ulink>.
1524 </para>
1525 </listitem>
1526 <listitem>
1527 <para>
1528 Ocaml related packages have their own policy, found in
1529 &file-ocaml-policy; from the <systemitem
1530 role="package">ocaml</systemitem> package.  A good example is the <systemitem
1531 role="package">camlzip</systemitem> source package.
1532 </para>
1533 </listitem>
1534 <listitem>
1535 <para>
1536 Packages providing XML or SGML DTDs should conform to the recommendations found
1537 in the <systemitem role="package">sgml-base-doc</systemitem> package.
1538 </para>
1539 </listitem>
1540 <listitem>
1541 <para>
1542 Lisp packages should register themselves with <systemitem
1543 role="package">common-lisp-controller</systemitem>, about which see
1544 &file-lisp-controller;.
1545 </para>
1546 </listitem>
1547 <!-- TODO: mozilla extension policy, once that becomes available -->
1548 </itemizedlist>
1549 </section>
1551 <!--
1552 <section id="custom-config-files">
1553 <title>Custom configuration files</title>
1554 <para>
1555 FIXME: speak of "ucf", explain solution with a template,
1556 explain conf.d directories
1557 </para>
1558 </section>
1559 <section id="config-with-db">
1560 <title>Use of an external database</title>
1561 <para>
1562 FIXME: The software may require a database that you need to setup.
1563 But the database may be local or distant. Thus you can't depend
1564 on a database server but just on the corresponding library.
1566 sympa may be an example package
1567 </para>
1568 </section>
1569 -->
1571 <section id="bpp-archindepdata">
1572 <title>Architecture-independent data</title>
1573 <para>
1574 It is not uncommon to have a large amount of architecture-independent data
1575 packaged with a program.  For example, audio files, a collection of icons,
1576 wallpaper patterns, or other graphic files.  If the size of this data is
1577 negligible compared to the size of the rest of the package, it's probably best
1578 to keep it all in a single package.
1579 </para>
1580 <para>
1581 However, if the size of the data is considerable, consider splitting it out
1582 into a separate, architecture-independent package (_all.deb).  By doing this,
1583 you avoid needless duplication of the same data into eleven or more .debs, one
1584 per each architecture.  While this adds some extra overhead into the
1585 <filename>Packages</filename> files, it saves a lot of disk space on Debian
1586 mirrors.  Separating out architecture-independent data also reduces processing
1587 time of <command>lintian</command> (see <xref
1588 linkend="tools-lint"/> ) when run over the entire Debian archive.
1589 </para>
1590 </section>
1592 <section id="bpp-locale">
1593 <title>Needing a certain locale during build</title>
1594 <para>
1595 If you need a certain locale during build, you can create a temporary file via
1596 this trick:
1597 </para>
1598 <para>
1599 If you set <varname>LOCPATH</varname> to the equivalent of <filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the name
1600 of the locale you generate, you should get what you want without being root.
1601 Something like this:
1602 </para>
1603 <screen>
1604 LOCALE_PATH=debian/tmpdir/usr/lib/locale
1608 mkdir -p $LOCALE_PATH
1611 # Using the locale
1613 </screen>
1614 </section>
1616 <section id="bpp-transition">
1617 <title>Make transition packages deborphan compliant</title>
1618 <para>
1619 Deborphan is a program for helping users to detect which packages can safely be
1620 removed from the system, i.e.  the ones that have no packages depending on
1621 them.  The default operation is to search only within the libs and oldlibs
1622 sections, to hunt down unused libraries.  But when passed the right argument,
1623 it tries to catch other useless packages.
1624 </para>
1625 <para>
1626 For example, with <literal>--guess-dummy</literal>, <command>deborphan</command>
1627 tries to search all transitional packages which were needed for upgrade but
1628 which can now safely be removed.
1629 For that, it looks for the string dummy or transitional in their short
1630 description.
1631 </para>
1632 <para>
1633 So, when you are creating such a package, please make sure to add this text to
1634 your short description.  If you are looking for examples, just run:
1635 <command>apt-cache search .|grep dummy</command> or
1636 <command>apt-cache search .|grep transitional</command>.
1637 </para>
1638 </section>
1640 <section id="bpp-origtargz">
1641 <title>Best practices for <filename>orig.tar.gz</filename> files</title>
1642 <para>
1643 There are two kinds of original source tarballs: Pristine source and repackaged
1644 upstream source.
1645 </para>
1646 <section id="pristinesource">
1647 <title>Pristine source</title>
1648 <para>
1649 The defining characteristic of a pristine source tarball is that the
1650 <literal>.orig.tar.gz</literal> file is byte-for-byte identical to a tarball officially
1651 distributed by the upstream author.  <footnote><para> We cannot prevent
1652 upstream authors from changing the tarball they distribute without also
1653 incrementing the version number, so there can be no guarantee that a pristine
1654 tarball is identical to what upstream <emphasis>currently</emphasis>
1655 distributing at any point in time.  All that can be expected is that it is
1656 identical to something that upstream once <emphasis>did</emphasis> distribute.
1657 If a difference arises later (say, if upstream notices that he wasn't using
1658 maximal compression in his original distribution and then
1659 re-<command>gzip</command>s it), that's just too bad.  Since there is no good
1660 way to upload a new <literal>.orig.tar.gz</literal> for the same version, there is not even any
1661 point in treating this situation as a bug.  </para> </footnote> This makes it
1662 possible to use checksums to easily verify that all changes between Debian's
1663 version and upstream's are contained in the Debian diff.  Also, if the original
1664 source is huge, upstream authors and others who already have the upstream
1665 tarball can save download time if they want to inspect your packaging in
1666 detail.
1667 </para>
1668 <para>
1669 There is no universally accepted guidelines that upstream authors follow
1670 regarding to the directory structure inside their tarball, but
1671 <command>dpkg-source</command> is nevertheless able to deal with most upstream
1672 tarballs as pristine source.  Its strategy is equivalent to the following:
1673 </para>
1674 <orderedlist numeration="arabic">
1675 <listitem>
1676 <para>
1677 It unpacks the tarball in an empty temporary directory by doing
1678 </para>
1679 <screen>
1680 zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
1681 </screen>
1682 </listitem>
1683 <listitem>
1684 <para>
1685 If, after this, the temporary directory contains nothing but one directory and
1686 no other files, <command>dpkg-source</command> renames that directory to
1687 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.  The
1688 name of the top-level directory in the tarball does not matter, and is
1689 forgotten.
1690 </para>
1691 </listitem>
1692 <listitem>
1693 <para>
1694 Otherwise, the upstream tarball must have been packaged without a common
1695 top-level directory (shame on the upstream author!).  In this case,
1696 <command>dpkg-source</command> renames the temporary directory
1697 <emphasis>itself</emphasis> to
1698 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.
1699 </para>
1700 </listitem>
1701 </orderedlist>
1702 </section>
1704 <section id="repackagedorigtargz">
1705 <title>Repackaged upstream source</title>
1706 <para>
1707 You <emphasis role="strong">should</emphasis> upload packages with a pristine
1708 source tarball if possible, but there are various reasons why it might not be
1709 possible.  This is the case if upstream does not distribute the source as
1710 gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
1711 that you must remove before uploading.
1712 </para>
1713 <para>
1714 In these cases the developer must construct a suitable <literal>.orig.tar.gz
1715 </literal> file himself.  We refer to such a tarball as a repackaged upstream 
1716 source.  Note that a repackaged upstream source is different from a 
1717 Debian-native package.  A repackaged source still comes with Debian-specific
1718 changes in a separate <literal>.diff.gz</literal> and still has a version
1719 number composed of <literal>&lt;upstream-version&gt;</literal> and
1720 <literal>&lt;debian-revision&gt;</literal>.
1721 </para>
1722 <para>
1723 There may be cases where it is desirable to repackage the source even though
1724 upstream distributes a <literal>.tar.gz</literal> that could in principle be
1725 used in its pristine form.  The most obvious is if
1726 <emphasis>significant</emphasis> space savings can be achieved by recompressing
1727 the tar archive or by removing genuinely useless cruft from the upstream
1728 archive.  Use your own discretion here, but be prepared to defend your decision
1729 if you repackage source that could have been pristine.
1730 </para>
1731 <para>
1732 A repackaged <literal>.orig.tar.gz</literal>
1733 </para>
1734 <orderedlist numeration="arabic">
1735 <listitem>
1736 <para>
1737 should be documented in the resulting source package.
1738 Detailed information on how the repackaged source was obtained,
1739 and on how this can be reproduced should be provided in
1740 <filename>debian/copyright</filename>.  It is also a good idea to provide a
1741 <literal>get-orig-source</literal> target in your
1742 <filename>debian/rules</filename> file that repeats the process, as described
1743 in the Policy Manual, <ulink
1744 url="&url-debian-policy;ch-source.html#s-debianrules">Main
1745 building script: debian/rules</ulink>.
1746 </para>
1747 </listitem>
1748 <listitem>
1749 <para>
1750 <emphasis role="strong">should not</emphasis> contain any file that does not
1751 come from the upstream author(s), or whose contents has been changed by you.
1752 <footnote><para> As a special exception, if the omission of non-free files
1753 would lead to the source failing to build without assistance from the Debian
1754 diff, it might be appropriate to instead edit the files, omitting only the
1755 non-free parts of them, and/or explain the situation in a README.source
1756 file in the root of the source tree.  But in that case please also urge the
1757 upstream author to make the non-free components easier seperable from the rest
1758 of the source.  </para> </footnote>
1759 </para>
1760 </listitem>
1761 <listitem>
1762 <para>
1763 <emphasis role="strong">should</emphasis>, except where impossible for legal
1764 reasons, preserve the entire building and portablility infrastructure provided
1765 by the upstream author.  For example, it is not a sufficient reason for
1766 omitting a file that it is used only when building on MS-DOS.  Similarly, a
1767 Makefile provided by upstream should not be omitted even if the first thing
1768 your <filename>debian/rules</filename> does is to overwrite it by running a
1769 configure script.
1770 </para>
1771 <para>
1772 (<emphasis>Rationale:</emphasis> It is common for Debian users who need to
1773 build software for non-Debian platforms to fetch the source from a Debian
1774 mirror rather than trying to locate a canonical upstream distribution point).
1775 </para>
1776 </listitem>
1777 <listitem>
1778 <para>
1779 <emphasis role="strong">should</emphasis> use
1780 <literal>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</literal> as the
1781 name of the top-level directory in its tarball.  This makes it possible to
1782 distinguish pristine tarballs from repackaged ones.
1783 </para>
1784 </listitem>
1785 <listitem>
1786 <para>
1787 <emphasis role="strong">should</emphasis> be gzipped with maximal compression.
1788 </para>
1789 </listitem>
1790 </orderedlist>
1791 <para>
1792 The canonical way to meet the latter two points is to let <literal>dpkg-source
1793 -b</literal> construct the repackaged tarball from an unpacked directory.
1794 </para>
1795 </section>
1797 <section id="changed-binfiles">
1798 <title>Changing binary files in <literal>diff.gz</literal></title>
1799 <para>
1800 Sometimes it is necessary to change binary files contained in the original
1801 tarball, or to add binary files that are not in it.  If this is done by simply
1802 copying the files into the debianized source tree,
1803 <command>dpkg-source</command> will not be able to handle this.  On the other
1804 hand, according to the guidelines given above, you cannot include such a
1805 changed binary file in a repackaged <filename>orig.tar.gz</filename>.  Instead,
1806 include the file in the <filename>debian</filename> directory in
1807 <command>uuencode</command>d (or similar) form <footnote><para> The file should
1808 have a name that makes it clear which binary file it encodes.  Usually, some
1809 postfix indicating the encoding should be appended to the original filename.
1810 Note that you don't need to depend on <systemitem
1811 role="package">sharutils</systemitem> to get the <command>uudecode</command>
1812 program if you use <command>perl</command>'s <literal>pack</literal> function.
1813 The code could look like
1814 </para>
1815 &example-uu;
1816 </footnote>.  The file would then be
1817 decoded and copied to its place during the build process.  Thus the change will
1818 be visible quite easy.
1819 </para>
1820 <para>
1821 Some packages use <command>dbs</command> to manage patches to their upstream
1822 source, and always create a new <literal>orig.tar.gz</literal> file that
1823 contains the real <literal>orig.tar.gz</literal> in its toplevel directory.
1824 This is questionable with respect to the preference for pristine source.  On
1825 the other hand, it is easy to modify or add binary files in this case: Just put
1826 them into the newly created <literal>orig.tar.gz</literal> file, besides the
1827 real one, and copy them to the right place during the build process.
1828 </para>
1829 </section>
1831 </section>
1833 <section id="bpp-dbg">
1834 <title>Best practices for debug packages</title>
1835 <para>
1836 A debug package is a package with a name ending in -dbg, that contains
1837 additional information that gdb can use.  Since Debian binaries are stripped by
1838 default, debugging information, including function names and line numbers, is
1839 otherwise not available when running gdb on Debian binaries.  Debug packages
1840 allow users who need this additional debugging information to install it,
1841 without bloating a regular system with the information.
1842 </para>
1843 <para>
1844 It is up to a package's maintainer whether to create a debug package or not.
1845 Maintainers are encouraged to create debug packages for library packages, since
1846 this can aid in debugging many programs linked to a library.  In general, debug
1847 packages do not need to be added for all programs; doing so would bloat the
1848 archive.  But if a maintainer finds that users often need a debugging version
1849 of a program, it can be worthwhile to make a debug package for it.  Programs
1850 that are core infrastructure, such as apache and the X server are also good
1851 candidates for debug packages.
1852 </para>
1853 <para>
1854 Some debug packages may contain an entire special debugging build of a library
1855 or other binary, but most of them can save space and build time by instead
1856 containing separated debugging symbols that gdb can find and load on the fly
1857 when debugging a program or library.  The convention in Debian is to keep these
1858 symbols in <filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where
1859 <replaceable>path</replaceable> is the path to the executable or library.  For
1860 example, debugging symbols for <filename>/usr/bin/foo</filename> go in
1861 <filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for
1862 <filename>/usr/lib/</filename> go in
1863 <filename>/usr/lib/debug/usr/lib/</filename>.
1864 </para>
1865 <para>
1866 The debugging symbols can be extracted from an object file using <command>
1867 objcopy --only-keep-debug</command>.  Then the object file can be stripped,
1868 and <command>objcopy --add-gnu-debuglink</command> used to specify the path
1869 to the debugging symbol file. 
1870 <citerefentry> <refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum>
1871 </citerefentry> explains in detail how this works.
1872 </para>
1873 <para>
1874 The <command>dh_strip</command> command in debhelper supports creating debug
1875 packages, and can take care of using <command>objcopy</command> to separate
1876 out the debugging symbols for you.  If your package uses debhelper, all you
1877 need to do is call <command>dh_strip --dbg-package=libfoo-dbg</command>, and
1878 add an entry to <filename>debian/control</filename> for the debug package.
1879 </para>
1880 <para>
1881 Note that the debug package should depend on the package that it provides
1882 debugging symbols for, and this dependency should be versioned.  For example:
1883 </para>
1884 <screen>
1885 Depends: libfoo (= ${binary:Version})
1886 </screen>
1887 </section>
1889 </section>
1891 </chapter>