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: 2008-08-08 11:33-0300\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"
15 "Content-Type: text/plain; charset=utf-8\n"
16 "Content-Transfer-Encoding: ENCODING"
18 # type: Content of: <chapter><title>
19 #: best-pkging-practices.dbk:7
20 msgid "Best Packaging Practices"
23 # type: Content of: <chapter><para>
24 #: best-pkging-practices.dbk:9
26 "Debian's quality is largely due to the <ulink "
27 "url=\"&url-debian-policy;\">Debian Policy</ulink>, which defines explicit "
28 "baseline requirements which all Debian packages must fulfill. Yet there is "
29 "also a shared history of experience which goes beyond the Debian Policy, an "
30 "accumulation of years of experience in packaging. Many very talented people "
31 "have created great tools, tools which help you, the Debian maintainer, "
32 "create and maintain excellent packages."
35 # type: Content of: <chapter><para>
36 #: best-pkging-practices.dbk:18
38 "This chapter provides some best practices for Debian developers. All "
39 "recommendations are merely that, and are not requirements or policy. These "
40 "are just some subjective hints, advice and pointers collected from Debian "
41 "developers. Feel free to pick and choose whatever works best for you."
44 # type: Content of: <chapter><section><title>
45 #: best-pkging-practices.dbk:24
46 msgid "Best practices for <filename>debian/rules</filename>"
49 # type: Content of: <chapter><section><para>
50 #: best-pkging-practices.dbk:26
52 "The following recommendations apply to the <filename>debian/rules</filename> "
53 "file. Since <filename>debian/rules</filename> controls the build process "
54 "and selects the files which go into the package (directly or indirectly), "
55 "it's usually the file maintainers spend the most time on."
58 # type: Content of: <chapter><section><section><title>
59 #: best-pkging-practices.dbk:32
60 msgid "Helper scripts"
63 # type: Content of: <chapter><section><section><para>
64 #: best-pkging-practices.dbk:34
66 "The rationale for using helper scripts in <filename>debian/rules</filename> "
67 "is that they let maintainers use and share common logic among many "
68 "packages. Take for instance the question of installing menu entries: you "
69 "need to put the file into <filename>/usr/share/menu</filename> (or "
70 "<filename>/usr/lib/menu</filename> for executable binary menufiles, if this "
71 "is needed), and add commands to the maintainer scripts to register and "
72 "unregister the menu entries. Since this is a very common thing for packages "
73 "to do, why should each maintainer rewrite all this on their own, sometimes "
74 "with bugs? Also, supposing the menu directory changed, every package would "
78 # type: Content of: <chapter><section><section><para>
79 #: best-pkging-practices.dbk:45
81 "Helper scripts take care of these issues. Assuming you comply with the "
82 "conventions expected by the helper script, the helper takes care of all the "
83 "details. Changes in policy can be made in the helper script; then packages "
84 "just need to be rebuilt with the new version of the helper and no other "
88 # type: Content of: <chapter><section><section><para>
89 #: best-pkging-practices.dbk:52
91 "<xref linkend=\"tools\"/> contains a couple of different helpers. The most "
92 "common and best (in our opinion) helper system is <systemitem "
93 "role=\"package\">debhelper</systemitem>. Previous helper systems, such as "
94 "<systemitem role=\"package\">debmake</systemitem>, were monolithic: you "
95 "couldn't pick and choose which part of the helper you found useful, but had "
96 "to use the helper to do everything. <systemitem "
97 "role=\"package\">debhelper</systemitem>, however, is a number of separate "
98 "little <command>dh_*</command> programs. For instance, "
99 "<command>dh_installman</command> installs and compresses man pages, "
100 "<command>dh_installmenu</command> installs menu files, and so on. Thus, it "
101 "offers enough flexibility to be able to use the little helper scripts, where "
102 "useful, in conjunction with hand-crafted commands in "
103 "<filename>debian/rules</filename>."
106 # type: Content of: <chapter><section><section><para>
107 #: best-pkging-practices.dbk:66
109 "You can get started with <systemitem role=\"package\">debhelper</systemitem> "
110 "by reading <citerefentry> <refentrytitle>debhelper</refentrytitle> "
111 "<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that "
112 "come with the package. <command>dh_make</command>, from the <systemitem "
113 "role=\"package\">dh-make</systemitem> package (see <xref "
114 "linkend=\"dh-make\"/> ), can be used to convert a vanilla source package to "
115 "a <systemitem role=\"package\">debhelper</systemitem>ized package. This "
116 "shortcut, though, should not convince you that you do not need to bother "
117 "understanding the individual <command>dh_*</command> helpers. If you are "
118 "going to use a helper, you do need to take the time to learn to use that "
119 "helper, to learn its expectations and behavior."
122 # type: Content of: <chapter><section><section><para>
123 #: best-pkging-practices.dbk:79
125 "Some people feel that vanilla <filename>debian/rules</filename> files are "
126 "better, since you don't have to learn the intricacies of any helper system. "
127 "This decision is completely up to you. Use what works for you. Many "
128 "examples of vanilla <filename>debian/rules</filename> files are available at "
129 "<ulink url=\"&url-rules-files;\"></ulink>."
132 # type: Content of: <chapter><section><section><title>
133 #: best-pkging-practices.dbk:88
134 msgid "Separating your patches into multiple files"
137 # type: Content of: <chapter><section><section><para>
138 #: best-pkging-practices.dbk:90
140 "Big, complex packages may have many bugs that you need to deal with. If you "
141 "correct a number of bugs directly in the source, and you're not careful, it "
142 "can get hard to differentiate the various patches that you applied. It can "
143 "get quite messy when you have to update the package to a new upstream "
144 "version which integrates some of the fixes (but not all). You can't take "
145 "the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
146 "out which patch sets to back out as a unit as bugs are fixed upstream."
149 # type: Content of: <chapter><section><section><para>
150 #: best-pkging-practices.dbk:99
152 "Unfortunately, the packaging system as such currently doesn't provide for "
153 "separating the patches into several files. Nevertheless, there are ways to "
154 "separate patches: the patch files are shipped within the Debian patch file "
155 "(<filename>.diff.gz</filename>), usually within the "
156 "<filename>debian/</filename> directory. The only difference is that they "
157 "aren't applied immediately by dpkg-source, but by the "
158 "<literal>build</literal> rule of <filename>debian/rules</filename>. "
159 "Conversely, they are reverted in the <literal>clean</literal> rule."
162 # type: Content of: <chapter><section><section><para>
163 #: best-pkging-practices.dbk:109
165 "<command>dbs</command> is one of the more popular approaches to this. It "
166 "does all of the above, and provides a facility for creating new and updating "
167 "old patches. See the package <systemitem role=\"package\">dbs</systemitem> "
168 "for more information and <systemitem role=\"package\">hello-dbs</systemitem> "
172 # type: Content of: <chapter><section><section><para>
173 #: best-pkging-practices.dbk:116
175 "<command>dpatch</command> also provides these facilities, but it's intended "
176 "to be even easier to use. See the package <systemitem "
177 "role=\"package\">dpatch</systemitem> for documentation and examples (in "
178 "<filename>/usr/share/doc/dpatch</filename>)."
181 # type: Content of: <chapter><section><section><title>
182 #: best-pkging-practices.dbk:124
183 msgid "Multiple binary packages"
186 # type: Content of: <chapter><section><section><para>
187 #: best-pkging-practices.dbk:126
189 "A single source package will often build several binary packages, either to "
190 "provide several flavors of the same software (e.g., the <systemitem "
191 "role=\"package\">vim</systemitem> source package) or to make several small "
192 "packages instead of a big one (e.g., so the user can install only the subset "
193 "needed, and thus save some disk space)."
196 # type: Content of: <chapter><section><section><para>
197 #: best-pkging-practices.dbk:133
199 "The second case can be easily managed in <filename>debian/rules</filename>. "
200 "You just need to move the appropriate files from the build directory into "
201 "the package's temporary trees. You can do this using "
202 "<command>install</command> or <command>dh_install</command> from <systemitem "
203 "role=\"package\">debhelper</systemitem>. Be sure to check the different "
204 "permutations of the various packages, ensuring that you have the "
205 "inter-package dependencies set right in <filename>debian/control</filename>."
208 # type: Content of: <chapter><section><section><para>
209 #: best-pkging-practices.dbk:142
211 "The first case is a bit more difficult since it involves multiple recompiles "
212 "of the same software but with different configuration options. The "
213 "<systemitem role=\"package\">vim</systemitem> source package is an example "
214 "of how to manage this using an hand-crafted "
215 "<filename>debian/rules</filename> file."
218 # type: Content of: <chapter><section><title>
219 #: best-pkging-practices.dbk:154
220 msgid "Best practices for <filename>debian/control</filename>"
223 # type: Content of: <chapter><section><para>
224 #: best-pkging-practices.dbk:156
226 "The following practices are relevant to the "
227 "<filename>debian/control</filename> file. They supplement the <ulink "
228 "url=\"&url-debian-policy;ch-binary.html#s-descriptions\">Policy on package "
229 "descriptions</ulink>."
232 # type: Content of: <chapter><section><para>
233 #: best-pkging-practices.dbk:162
235 "The description of the package, as defined by the corresponding field in the "
236 "<filename>control</filename> file, contains both the package synopsis and "
237 "the long description for the package. <xref linkend=\"bpp-desc-basics\"/> "
238 "describes common guidelines for both parts of the package description. "
239 "Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
240 "specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
241 "guidelines specific to the description."
244 # type: Content of: <chapter><section><section><title>
245 #: best-pkging-practices.dbk:171
246 msgid "General guidelines for package descriptions"
249 # type: Content of: <chapter><section><section><para>
250 #: best-pkging-practices.dbk:173
252 "The package description should be written for the average likely user, the "
253 "average person who will use and benefit from the package. For instance, "
254 "development packages are for developers, and can be technical in their "
255 "language. More general-purpose applications, such as editors, should be "
256 "written for a less technical user."
259 # type: Content of: <chapter><section><section><para>
260 #: best-pkging-practices.dbk:180
262 "Our review of package descriptions lead us to conclude that most package "
263 "descriptions are technical, that is, are not written to make sense for "
264 "non-technical users. Unless your package really is only for technical "
265 "users, this is a problem."
268 # type: Content of: <chapter><section><section><para>
269 #: best-pkging-practices.dbk:186
271 "How do you write for non-technical users? Avoid jargon. Avoid referring to "
272 "other applications or frameworks that the user might not be familiar with — "
273 "GNOME or KDE is fine, since users are probably familiar with these terms, "
274 "but GTK+ is probably not. Try not to assume any knowledge at all. If you "
275 "must use technical terms, introduce them."
278 # type: Content of: <chapter><section><section><para>
279 #: best-pkging-practices.dbk:193
281 "Be objective. Package descriptions are not the place for advocating your "
282 "package, no matter how much you love it. Remember that the reader may not "
283 "care about the same things you care about."
286 # type: Content of: <chapter><section><section><para>
287 #: best-pkging-practices.dbk:198
289 "References to the names of any other software packages, protocol names, "
290 "standards, or specifications should use their canonical forms, if one "
291 "exists. For example, use X Window System, X11, or X; not X Windows, "
292 "X-Windows, or X Window. Use GTK+, not GTK or gtk. Use GNOME, not Gnome. "
293 "Use PostScript, not Postscript or postscript."
296 # type: Content of: <chapter><section><section><para>
297 #: best-pkging-practices.dbk:205
299 "If you are having problems writing your description, you may wish to send it "
300 "along to &email-debian-l10n-english; and request feedback."
303 # type: Content of: <chapter><section><section><title>
304 #: best-pkging-practices.dbk:211
305 msgid "The package synopsis, or short description"
308 # type: Content of: <chapter><section><section><para>
309 #: best-pkging-practices.dbk:213
311 "The synopsis line (the short description) should be concise. It must not "
312 "repeat the package's name (this is policy)."
315 # type: Content of: <chapter><section><section><para>
316 #: best-pkging-practices.dbk:217
318 "It's a good idea to think of the synopsis as an appositive clause, not a "
319 "full sentence. An appositive clause is defined in WordNet as a grammatical "
320 "relation between a word and a noun phrase that follows, e.g., Rudolph the "
321 "red-nosed reindeer. The appositive clause here is red-nosed reindeer. "
322 "Since the synopsis is a clause, rather than a full sentence, we recommend "
323 "that it neither start with a capital nor end with a full stop (period). It "
324 "should also not begin with an article, either definite (the) or indefinite "
328 # type: Content of: <chapter><section><section><para>
329 #: best-pkging-practices.dbk:226
331 "It might help to imagine that the synopsis is combined with the package name "
332 "in the following way:"
335 # type: Content of: <chapter><section><section><screen>
336 #: best-pkging-practices.dbk:229
340 "<replaceable>package-name</replaceable> is a "
341 "<replaceable>synopsis</replaceable>.\n"
344 # type: Content of: <chapter><section><section><para>
345 #: best-pkging-practices.dbk:233
346 msgid "Alternatively, it might make sense to think of it as"
349 # type: Content of: <chapter><section><section><screen>
350 #: best-pkging-practices.dbk:235
354 "<replaceable>package-name</replaceable> is "
355 "<replaceable>synopsis</replaceable>.\n"
358 # type: Content of: <chapter><section><section><para>
359 #: best-pkging-practices.dbk:239
360 msgid "or, if the package name itself is a plural (such as developers-tools)"
363 # type: Content of: <chapter><section><section><screen>
364 #: best-pkging-practices.dbk:241
368 "<replaceable>package-name</replaceable> are "
369 "<replaceable>synopsis</replaceable>.\n"
372 # type: Content of: <chapter><section><section><para>
373 #: best-pkging-practices.dbk:245
375 "This way of forming a sentence from the package name and synopsis should be "
376 "considered as a heuristic and not a strict rule. There are some cases where "
377 "it doesn't make sense to try to form a sentence."
380 # type: Content of: <chapter><section><section><title>
381 #: best-pkging-practices.dbk:252
382 msgid "The long description"
385 # type: Content of: <chapter><section><section><para>
386 #: best-pkging-practices.dbk:254
388 "The long description is the primary information available to the user about "
389 "a package before they install it. It should provide all the information "
390 "needed to let the user decide whether to install the package. Assume that "
391 "the user has already read the package synopsis."
394 # type: Content of: <chapter><section><section><para>
395 #: best-pkging-practices.dbk:260
396 msgid "The long description should consist of full and complete sentences."
399 # type: Content of: <chapter><section><section><para>
400 #: best-pkging-practices.dbk:263
402 "The first paragraph of the long description should answer the following "
403 "questions: what does the package do? what task does it help the user "
404 "accomplish? It is important to describe this in a non-technical way, unless "
405 "of course the audience for the package is necessarily technical."
408 # type: Content of: <chapter><section><section><para>
409 #: best-pkging-practices.dbk:269
411 "The following paragraphs should answer the following questions: Why do I as "
412 "a user need this package? What other features does the package have? What "
413 "outstanding features and deficiencies are there compared to other packages "
414 "(e.g., if you need X, use Y instead)? Is this package related to other "
415 "packages in some way that is not handled by the package manager (e.g., this "
416 "is the client for the foo server)?"
419 # type: Content of: <chapter><section><section><para>
420 #: best-pkging-practices.dbk:277
422 "Be careful to avoid spelling and grammar mistakes. Ensure that you "
423 "spell-check it. Both <command>ispell</command> and "
424 "<command>aspell</command> have special modes for checking "
425 "<filename>debian/control</filename> files:"
428 # type: Content of: <chapter><section><section><screen>
429 #: best-pkging-practices.dbk:281
433 "ispell -d american -g debian/control\n"
436 # type: Content of: <chapter><section><section><screen>
437 #: best-pkging-practices.dbk:284
441 "aspell -d en -D -c debian/control\n"
444 # type: Content of: <chapter><section><section><para>
445 #: best-pkging-practices.dbk:288
447 "Users usually expect these questions to be answered in the package "
451 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
452 #: best-pkging-practices.dbk:293
454 "What does the package do? If it is an add-on to another package, then the "
455 "short description of the package we are an add-on to should be put in here."
458 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
459 #: best-pkging-practices.dbk:299
461 "Why should I want this package? This is related to the above, but not the "
462 "same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
463 "LDAP and IMAP, has features X, Y, and Z)."
466 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
467 #: best-pkging-practices.dbk:306
469 "If this package should not be installed directly, but is pulled in by "
470 "another package, this should be mentioned."
473 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
474 #: best-pkging-practices.dbk:312
476 "If the package is <literal>experimental</literal>, or there are other "
477 "reasons it should not be used, if there are other packages that should be "
478 "used instead, it should be here as well."
481 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
482 #: best-pkging-practices.dbk:319
484 "How is this package different from the competition? Is it a better "
485 "implementation? more features? different features? Why should I choose this "
489 # type: Content of: <chapter><section><section><title>
490 #: best-pkging-practices.dbk:332
491 msgid "Upstream home page"
494 # type: Content of: <chapter><section><section><para>
495 #: best-pkging-practices.dbk:334
497 "We recommend that you add the URL for the package's home page in the "
498 "<literal>Homepage</literal> field of the <literal>Source</literal> section "
499 "in <filename>debian/control</filename>. Adding this information in the "
500 "package description itself is considered deprecated."
503 # type: Content of: <chapter><section><section><title>
504 #: best-pkging-practices.dbk:342
505 msgid "Version Control System location"
508 # type: Content of: <chapter><section><section><para>
509 #: best-pkging-practices.dbk:344
511 "There are additional fields for the location of the Version Control System "
512 "in <filename>debian/control</filename>."
515 # type: Content of: <chapter><section><section><section><title>
516 #: best-pkging-practices.dbk:348
520 # type: Content of: <chapter><section><section><section><para>
521 #: best-pkging-practices.dbk:350
523 "Value of this field should be a <literal>http://</literal> URL pointing to a "
524 "web-browsable copy of the Version Control System repository used to maintain "
525 "the given package, if available."
528 # type: Content of: <chapter><section><section><section><para>
529 #: best-pkging-practices.dbk:355
531 "The information is meant to be useful for the final user, willing to browse "
532 "the latest work done on the package (e.g. when looking for the patch fixing "
533 "a bug tagged as <literal>pending</literal> in the bug tracking system)."
536 # type: Content of: <chapter><section><section><section><title>
537 #: best-pkging-practices.dbk:362
541 # type: Content of: <chapter><section><section><section><para>
542 #: best-pkging-practices.dbk:364
544 "Value of this field should be a string identifying unequivocally the "
545 "location of the Version Control System repository used to maintain the given "
546 "package, if available. <literal>*</literal> identify the Version Control "
547 "System; currently the following systems are supported by the package "
548 "tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
549 "<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
550 "<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
551 "<literal>svn</literal> (Subversion). It is allowed to specify different VCS "
552 "fields for the same package: they will all be shown in the PTS web "
556 # type: Content of: <chapter><section><section><section><para>
557 #: best-pkging-practices.dbk:375
559 "The information is meant to be useful for a user knowledgeable in the given "
560 "Version Control System and willing to build the current version of a package "
561 "from the VCS sources. Other uses of this information might include "
562 "automatic building of the latest VCS version of the given package. To this "
563 "end the location pointed to by the field should better be version agnostic "
564 "and point to the main branch (for VCSs supporting such a concept). Also, "
565 "the location pointed to should be accessible to the final user; fulfilling "
566 "this requirement might imply pointing to an anonymous access of the "
567 "repository instead of pointing to an SSH-accessible version of the same."
570 # type: Content of: <chapter><section><section><section><para>
571 #: best-pkging-practices.dbk:386
573 "In the following example, an instance of the field for a Subversion "
574 "repository of the <systemitem role=\"package\">vim</systemitem> package is "
575 "shown. Note how the URL is in the <literal>svn://</literal> scheme (instead "
576 "of <literal>svn+ssh://</literal>) and how it points to the "
577 "<filename>trunk/</filename> branch. The use of the "
578 "<literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields "
579 "described above is also shown."
582 # type: Content of: <chapter><section><section><section><screen>
583 #: best-pkging-practices.dbk:394
588 " Section: editors\n"
589 " Priority: optional\n"
591 " Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
592 " Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim\n"
593 " Homepage: http://www.vim.org\n"
596 # type: Content of: <chapter><section><title>
597 #: best-pkging-practices.dbk:410
598 msgid "Best practices for <filename>debian/changelog</filename>"
601 # type: Content of: <chapter><section><para>
602 #: best-pkging-practices.dbk:412
604 "The following practices supplement the <ulink "
605 "url=\"&url-debian-policy;ch-docs.html#s-changelogs\">Policy on changelog "
609 # type: Content of: <chapter><section><section><title>
610 #: best-pkging-practices.dbk:417
611 msgid "Writing useful changelog entries"
614 # type: Content of: <chapter><section><section><para>
615 #: best-pkging-practices.dbk:419
617 "The changelog entry for a package revision documents changes in that "
618 "revision, and only them. Concentrate on describing significant and "
619 "user-visible changes that were made since the last version."
622 # type: Content of: <chapter><section><section><para>
623 #: best-pkging-practices.dbk:424
625 "Focus on <emphasis>what</emphasis> was changed — who, how and when are "
626 "usually less important. Having said that, remember to politely attribute "
627 "people who have provided notable help in making the package (e.g., those who "
628 "have sent in patches)."
631 # type: Content of: <chapter><section><section><para>
632 #: best-pkging-practices.dbk:430
634 "There's no need to elaborate the trivial and obvious changes. You can also "
635 "aggregate several changes in one entry. On the other hand, don't be overly "
636 "terse if you have undertaken a major change. Be especially clear if there "
637 "are changes that affect the behaviour of the program. For further "
638 "explanations, use the <filename>README.Debian</filename> file."
641 # type: Content of: <chapter><section><section><para>
642 #: best-pkging-practices.dbk:437
644 "Use common English so that the majority of readers can comprehend it. Avoid "
645 "abbreviations, tech-speak and jargon when explaining changes that close "
646 "bugs, especially for bugs filed by users that did not strike you as "
647 "particularly technically savvy. Be polite, don't swear."
650 # type: Content of: <chapter><section><section><para>
651 #: best-pkging-practices.dbk:443
653 "It is sometimes desirable to prefix changelog entries with the names of the "
654 "files that were changed. However, there's no need to explicitly list each "
655 "and every last one of the changed files, especially if the change was small "
656 "or repetitive. You may use wildcards."
659 # type: Content of: <chapter><section><section><para>
660 #: best-pkging-practices.dbk:449
662 "When referring to bugs, don't assume anything. Say what the problem was, "
663 "how it was fixed, and append the closes: #nnnnn string. See <xref "
664 "linkend=\"upload-bugfix\"/> for more information."
667 # type: Content of: <chapter><section><section><title>
668 #: best-pkging-practices.dbk:456
669 msgid "Common misconceptions about changelog entries"
672 # type: Content of: <chapter><section><section><para>
673 #: best-pkging-practices.dbk:458
675 "The changelog entries should <emphasis role=\"strong\">not</emphasis> "
676 "document generic packaging issues (Hey, if you're looking for foo.conf, it's "
677 "in /etc/blah/.), since administrators and users are supposed to be at least "
678 "remotely acquainted with how such things are generally arranged on Debian "
679 "systems. Do, however, mention if you change the location of a configuration "
683 # type: Content of: <chapter><section><section><para>
684 #: best-pkging-practices.dbk:466
686 "The only bugs closed with a changelog entry should be those that are "
687 "actually fixed in the same package revision. Closing unrelated bugs in the "
688 "changelog is bad practice. See <xref linkend=\"upload-bugfix\"/> ."
691 # type: Content of: <chapter><section><section><para>
692 #: best-pkging-practices.dbk:471
694 "The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
695 "used for random discussion with bug reporters (I don't see segfaults when "
696 "starting foo with option bar; send in more info), general statements on "
697 "life, the universe and everything (sorry this upload took me so long, but I "
698 "caught the flu), or pleas for help (the bug list on this package is huge, "
699 "please lend me a hand). Such things usually won't be noticed by their "
700 "target audience, but may annoy people who wish to read information about "
701 "actual changes in the package. See <xref linkend=\"bug-answering\"/> for "
702 "more information on how to use the bug tracking system."
705 # type: Content of: <chapter><section><section><para>
706 #: best-pkging-practices.dbk:482
708 "It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
709 "in the first changelog entry of the proper maintainer upload. As we have "
710 "version tracking now, it is enough to keep the NMUed changelog entries and "
711 "just mention this fact in your own changelog entry."
714 # type: Content of: <chapter><section><section><title>
715 #: best-pkging-practices.dbk:490
716 msgid "Common errors in changelog entries"
719 # type: Content of: <chapter><section><section><para>
720 #: best-pkging-practices.dbk:492
722 "The following examples demonstrate some common errors or examples of bad "
723 "style in changelog entries."
726 # type: Content of: <chapter><section><section><screen>
727 #: best-pkging-practices.dbk:495
731 " * Fixed all outstanding bugs.\n"
734 # type: Content of: <chapter><section><section><para>
735 #: best-pkging-practices.dbk:499
736 msgid "This doesn't tell readers anything too useful, obviously."
739 # type: Content of: <chapter><section><section><screen>
740 #: best-pkging-practices.dbk:501
744 " * Applied patch from Jane Random.\n"
747 # type: Content of: <chapter><section><section><para>
748 #: best-pkging-practices.dbk:505
749 msgid "What was the patch about?"
752 # type: Content of: <chapter><section><section><screen>
753 #: best-pkging-practices.dbk:507
757 " * Late night install target overhaul.\n"
760 # type: Content of: <chapter><section><section><para>
761 #: best-pkging-practices.dbk:511
763 "Overhaul which accomplished what? Is the mention of late night supposed to "
764 "remind us that we shouldn't trust that code?"
767 # type: Content of: <chapter><section><section><screen>
768 #: best-pkging-practices.dbk:514
772 " * Fix vsync FU w/ ancient CRTs.\n"
775 # type: Content of: <chapter><section><section><para>
776 #: best-pkging-practices.dbk:518
778 "Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
779 "curse word!) was actually about, or how it was fixed."
782 # type: Content of: <chapter><section><section><screen>
783 #: best-pkging-practices.dbk:521
787 " * This is not a bug, closes: #nnnnnn.\n"
790 # type: Content of: <chapter><section><section><para>
791 #: best-pkging-practices.dbk:525
793 "First of all, there's absolutely no need to upload the package to convey "
794 "this information; instead, use the bug tracking system. Secondly, there's "
795 "no explanation as to why the report is not a bug."
798 # type: Content of: <chapter><section><section><screen>
799 #: best-pkging-practices.dbk:529
803 " * Has been fixed for ages, but I forgot to close; closes: #54321.\n"
806 # type: Content of: <chapter><section><section><para>
807 #: best-pkging-practices.dbk:533
809 "If for some reason you didn't mention the bug number in a previous changelog "
810 "entry, there's no problem, just close the bug normally in the BTS. There's "
811 "no need to touch the changelog file, presuming the description of the fix is "
812 "already in (this applies to the fixes by the upstream authors/maintainers as "
813 "well, you don't have to track bugs that they fixed ages ago in your "
817 # type: Content of: <chapter><section><section><screen>
818 #: best-pkging-practices.dbk:539
822 " * Closes: #12345, #12346, #15432\n"
825 # type: Content of: <chapter><section><section><para>
826 #: best-pkging-practices.dbk:543
828 "Where's the description? If you can't think of a descriptive message, start "
829 "by inserting the title of each different bug."
832 # type: Content of: <chapter><section><section><title>
833 #: best-pkging-practices.dbk:549
834 msgid "Supplementing changelogs with NEWS.Debian files"
837 # type: Content of: <chapter><section><section><para>
838 #: best-pkging-practices.dbk:551
840 "Important news about changes in a package can also be put in <filename> "
841 "NEWS.Debian</filename> files. The news will be displayed by tools like "
842 "apt-listchanges, before all the rest of the changelogs. This is the "
843 "preferred means to let the user know about significant changes in a "
844 "package. It is better than using debconf notes since it is less annoying "
845 "and the user can go back and refer to the <filename> NEWS.Debian</filename> "
846 "file after the install. And it's better than listing major changes in "
847 "<filename>README.Debian</filename>, since the user can easily miss such "
851 # type: Content of: <chapter><section><section><para>
852 #: best-pkging-practices.dbk:562
854 "The file format is the same as a debian changelog file, but leave off the "
855 "asterisks and describe each news item with a full paragraph when necessary "
856 "rather than the more concise summaries that would go in a changelog. It's a "
857 "good idea to run your file through <literal>dpkg-parsechangelog</literal> to "
858 "check its formatting as it will not be automatically checked during build as "
859 "the changelog is. Here is an example of a real <filename>NEWS.Debian "
863 # type: Content of: <chapter><section><section><screen>
864 #: best-pkging-practices.dbk:570
868 "cron (3.0pl1-74) unstable; urgency=low\n"
870 " The checksecurity script is no longer included with the cron package:\n"
871 " it now has its own package, checksecurity. If you liked the\n"
872 " functionality provided with that script, please install the new\n"
875 " -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 "
879 # type: Content of: <chapter><section><section><para>
880 #: best-pkging-practices.dbk:581
882 "The <filename>NEWS.Debian</filename> file is installed as <filename> "
883 "/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>. "
884 "It is compressed, and always has that name even in Debian native packages. "
885 "If you use <literal>debhelper</literal>, <literal>dh_installchangelogs "
886 "</literal> will install <filename>debian/NEWS</filename> files for you."
889 # type: Content of: <chapter><section><section><para>
890 #: best-pkging-practices.dbk:588
892 "Unlike changelog files, you need not update <filename>NEWS.Debian</filename> "
893 "files with every release. Only update them if you have something "
894 "particularly newsworthy that user should know about. If you have no news at "
895 "all, there's no need to ship a <filename>NEWS.Debian</filename> file in your "
896 "package. No news is good news!"
899 # type: Content of: <chapter><section><title>
900 #: best-pkging-practices.dbk:610
901 msgid "Best practices for maintainer scripts"
904 # type: Content of: <chapter><section><para>
905 #: best-pkging-practices.dbk:612
907 "Maintainer scripts include the files <filename>debian/postinst</filename>, "
908 "<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
909 "<filename>debian/postrm</filename>. These scripts take care of any package "
910 "installation or deinstallation setup which isn't handled merely by the "
911 "creation or removal of files and directories. The following instructions "
912 "supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
915 # type: Content of: <chapter><section><para>
916 #: best-pkging-practices.dbk:620
918 "Maintainer scripts must be idempotent. That means that you need to make "
919 "sure nothing bad will happen if the script is called twice where it would "
920 "usually be called once."
923 # type: Content of: <chapter><section><para>
924 #: best-pkging-practices.dbk:625
926 "Standard input and output may be redirected (e.g. into pipes) for logging "
927 "purposes, so don't rely on them being a tty."
930 # type: Content of: <chapter><section><para>
931 #: best-pkging-practices.dbk:629
933 "All prompting or interactive configuration should be kept to a minimum. "
934 "When it is necessary, you should use the <systemitem "
935 "role=\"package\">debconf</systemitem> package for the interface. Remember "
936 "that prompting in any case can only be in the <literal>configure</literal> "
937 "stage of the <filename>postinst</filename> script."
940 # type: Content of: <chapter><section><para>
941 #: best-pkging-practices.dbk:636
943 "Keep the maintainer scripts as simple as possible. We suggest you use pure "
944 "POSIX shell scripts. Remember, if you do need any bash features, the "
945 "maintainer script must have a bash shebang line. POSIX shell or Bash are "
946 "preferred to Perl, since they enable <systemitem "
947 "role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
950 # type: Content of: <chapter><section><para>
951 #: best-pkging-practices.dbk:643
953 "If you change your maintainer scripts, be sure to test package removal, "
954 "double installation, and purging. Be sure that a purged package is "
955 "completely gone, that is, it must remove any files created, directly or "
956 "indirectly, in any maintainer script."
959 # type: Content of: <chapter><section><para>
960 #: best-pkging-practices.dbk:649
962 "If you need to check for the existence of a command, you should use "
966 # type: Content of: <chapter><section><programlisting>
967 #: best-pkging-practices.dbk:652
969 msgid "if [ -x /usr/sbin/install-docs ]; then ..."
972 # type: Content of: <chapter><section><para>
973 #: best-pkging-practices.dbk:654
975 "If you don't wish to hard-code the path of a command in your maintainer "
976 "script, the following POSIX-compliant shell function may help:"
979 # type: Content of: <chapter><section><para>
980 #: best-pkging-practices.dbk:659
982 "You can use this function to search <literal>$PATH</literal> for a command "
983 "name, passed as an argument. It returns true (zero) if the command was "
984 "found, and false if not. This is really the most portable way, since "
985 "<literal>command -v</literal>, <command>type</command>, and "
986 "<command>which</command> are not POSIX."
989 # type: Content of: <chapter><section><para>
990 #: best-pkging-practices.dbk:666
992 "While <command>which</command> is an acceptable alternative, since it is "
993 "from the required <systemitem role=\"package\">debianutils</systemitem> "
994 "package, it's not on the root partition. That is, it's in "
995 "<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
996 "can't use it in scripts which are run before the <filename>/usr</filename> "
997 "partition is mounted. Most scripts won't have this problem, though."
1000 # type: Content of: <chapter><section><title>
1001 #: best-pkging-practices.dbk:676
1003 "Configuration management with <systemitem "
1004 "role=\"package\">debconf</systemitem>"
1007 # type: Content of: <chapter><section><para>
1008 #: best-pkging-practices.dbk:678
1010 "<systemitem role=\"package\">Debconf</systemitem> is a configuration "
1011 "management system which can be used by all the various packaging scripts "
1012 "(<filename>postinst</filename> mainly) to request feedback from the user "
1013 "concerning how to configure the package. Direct user interactions must now "
1014 "be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
1015 "interaction. This will enable non-interactive installations in the future."
1018 # type: Content of: <chapter><section><para>
1019 #: best-pkging-practices.dbk:686
1021 "Debconf is a great tool but it is often poorly used. Many common mistakes "
1022 "are listed in the <citerefentry> "
1023 "<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
1024 "</citerefentry> man page. It is something that you must read if you decide "
1025 "to use debconf. Also, we document some best practices here."
1028 # type: Content of: <chapter><section><para>
1029 #: best-pkging-practices.dbk:693
1031 "These guidelines include some writing style and typography recommendations, "
1032 "general considerations about debconf usage as well as more specific "
1033 "recommendations for some parts of the distribution (the installation system "
1037 # type: Content of: <chapter><section><section><title>
1038 #: best-pkging-practices.dbk:699
1039 msgid "Do not abuse debconf"
1042 # type: Content of: <chapter><section><section><para>
1043 #: best-pkging-practices.dbk:701
1045 "Since debconf appeared in Debian, it has been widely abused and several "
1046 "criticisms received by the Debian distribution come from debconf abuse with "
1047 "the need of answering a wide bunch of questions before getting any little "
1051 # type: Content of: <chapter><section><section><para>
1052 #: best-pkging-practices.dbk:707
1054 "Keep usage notes to what they belong: the NEWS.Debian, or README.Debian "
1055 "file. Only use notes for important notes which may directly affect the "
1056 "package usability. Remember that notes will always block the install until "
1057 "confirmed or bother the user by email."
1060 # type: Content of: <chapter><section><section><para>
1061 #: best-pkging-practices.dbk:713
1063 "Carefully choose the questions priorities in maintainer scripts. See "
1064 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1065 "<manvolnum>7</manvolnum> </citerefentry> for details about priorities. Most "
1066 "questions should use medium and low priorities."
1069 # type: Content of: <chapter><section><section><title>
1070 #: best-pkging-practices.dbk:721
1071 msgid "General recommendations for authors and translators"
1074 # type: Content of: <chapter><section><section><section><title>
1075 #: best-pkging-practices.dbk:723
1076 msgid "Write correct English"
1079 # type: Content of: <chapter><section><section><section><para>
1080 #: best-pkging-practices.dbk:725
1082 "Most Debian package maintainers are not native English speakers. So, "
1083 "writing properly phrased templates may not be easy for them."
1086 # type: Content of: <chapter><section><section><section><para>
1087 #: best-pkging-practices.dbk:729
1089 "Please use (and abuse) &email-debian-l10n-english; mailing list. Have your "
1090 "templates proofread."
1093 # type: Content of: <chapter><section><section><section><para>
1094 #: best-pkging-practices.dbk:733
1096 "Badly written templates give a poor image of your package, of your work...or "
1097 "even of Debian itself."
1100 # type: Content of: <chapter><section><section><section><para>
1101 #: best-pkging-practices.dbk:737
1103 "Avoid technical jargon as much as possible. If some terms sound common to "
1104 "you, they may be impossible to understand for others. If you cannot avoid "
1105 "them, try to explain them (use the extended description). When doing so, "
1106 "try to balance between verbosity and simplicity."
1109 # type: Content of: <chapter><section><section><section><title>
1110 #: best-pkging-practices.dbk:745
1111 msgid "Be kind to translators"
1114 # type: Content of: <chapter><section><section><section><para>
1115 #: best-pkging-practices.dbk:747
1117 "Debconf templates may be translated. Debconf, along with its sister package "
1118 "<command>po-debconf</command> offers a simple framework for getting "
1119 "templates translated by translation teams or even individuals."
1122 # type: Content of: <chapter><section><section><section><para>
1123 #: best-pkging-practices.dbk:752
1125 "Please use gettext-based templates. Install <systemitem "
1126 "role=\"package\">po-debconf</systemitem> on your development system and read "
1127 "its documentation (<literal>man po-debconf</literal> is a good start)."
1130 # type: Content of: <chapter><section><section><section><para>
1131 #: best-pkging-practices.dbk:757
1133 "Avoid changing templates too often. Changing templates text induces more "
1134 "work to translators which will get their translation fuzzied. If you plan "
1135 "changes to your original templates, please contact translators. Most active "
1136 "translators are very responsive and getting their work included along with "
1137 "your modified templates will save you additional uploads. If you use "
1138 "gettext-based templates, the translator's name and e-mail addresses are "
1139 "mentioned in the po files headers."
1142 # type: Content of: <chapter><section><section><section><para>
1143 #: best-pkging-practices.dbk:766
1145 "The use of the <command>podebconf-report-po</command> from the <systemitem "
1146 "role=\"package\">po-debconf</systemitem> package is highly recommended to "
1147 "warn translators which have incomplete translations and request them for "
1151 # type: Content of: <chapter><section><section><section><para>
1152 #: best-pkging-practices.dbk:771
1154 "If in doubt, you may also contact the translation team for a given language "
1155 "(debian-l10n-xxxxx@&lists-host;), or the &email-debian-i18n; mailing list."
1158 # type: Content of: <chapter><section><section><section><para>
1159 #: best-pkging-practices.dbk:776
1161 "Calls for translations posted to &email-debian-i18n; with the "
1162 "<filename>debian/po/templates.pot</filename> file attached or referenced in "
1163 "a URL are encouraged. Be sure to mentions in these calls for new "
1164 "translations which languages you have existing translations for, in order to "
1165 "avoid duplicate work."
1168 # type: Content of: <chapter><section><section><section><title>
1169 #: best-pkging-practices.dbk:785
1170 msgid "Unfuzzy complete translations when correcting typos and spelling"
1173 # type: Content of: <chapter><section><section><section><para>
1174 #: best-pkging-practices.dbk:787
1176 "When the text of a debconf template is corrected and you are <emphasis "
1177 "role=\"strong\">sure</emphasis> that the change does <emphasis "
1178 "role=\"strong\">not</emphasis> affect translations, please be kind to "
1179 "translators and unfuzzy their translations."
1182 # type: Content of: <chapter><section><section><section><para>
1183 #: best-pkging-practices.dbk:793
1185 "If you don't do so, the whole template will not be translated as long as a "
1186 "translator will send you an update."
1189 # type: Content of: <chapter><section><section><section><para>
1190 #: best-pkging-practices.dbk:797
1192 "To <literal>unfuzzy</literal> translations, you can proceed the following "
1196 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1197 #: best-pkging-practices.dbk:803
1199 "Put all incomplete PO files out of the way. You can check the completeness "
1200 "by using (needs the <systemitem role=\"package\">gettext</systemitem> "
1201 "package installed):"
1204 # type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1205 #: best-pkging-practices.dbk:807
1208 "for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null\n"
1209 "--statistics $i; done"
1212 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1213 #: best-pkging-practices.dbk:812
1215 "move all files which report either fuzzy strings to a temporary place. "
1216 "Files which report no fuzzy strings (only translated and untranslated) will "
1220 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1221 #: best-pkging-practices.dbk:819
1223 "now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
1224 "for the typos and check again that translation are not impacted (typos, "
1225 "spelling errors, sometimes typographical corrections are usually OK)"
1228 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1229 #: best-pkging-practices.dbk:826
1231 "run <command>debconf-updatepo</command>. This will fuzzy all strings you "
1232 "modified in translations. You can see this by running the above again"
1235 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1236 #: best-pkging-practices.dbk:832
1237 msgid "use the following command:"
1240 # type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1241 #: best-pkging-practices.dbk:834
1243 msgid "for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done"
1246 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1247 #: best-pkging-practices.dbk:838
1249 "move back to debian/po the files which showed fuzzy strings in the first "
1253 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1254 #: best-pkging-practices.dbk:843
1255 msgid "run <command>debconf-updatepo</command> again"
1258 # type: Content of: <chapter><section><section><section><title>
1259 #: best-pkging-practices.dbk:850
1260 msgid "Do not make assumptions about interfaces"
1263 # type: Content of: <chapter><section><section><section><para>
1264 #: best-pkging-practices.dbk:852
1266 "Templates text should not make reference to widgets belonging to some "
1267 "debconf interfaces. Sentences like If you answer Yes... have no meaning "
1268 "for users of graphical interfaces which use checkboxes for boolean "
1272 # type: Content of: <chapter><section><section><section><para>
1273 #: best-pkging-practices.dbk:857
1275 "String templates should also avoid mentioning the default values in their "
1276 "description. First, because this is redundant with the values seen by the "
1277 "users. Also, because these default values may be different from the "
1278 "maintainer choices (for instance, when the debconf database was preseeded)."
1281 # type: Content of: <chapter><section><section><section><para>
1282 #: best-pkging-practices.dbk:863
1284 "More generally speaking, try to avoid referring to user actions. Just give "
1288 # type: Content of: <chapter><section><section><section><title>
1289 #: best-pkging-practices.dbk:869
1290 msgid "Do not use first person"
1293 # type: Content of: <chapter><section><section><section><para>
1294 #: best-pkging-practices.dbk:871
1296 "You should avoid the use of first person (I will do this... or We "
1297 "recommend...). The computer is not a person and the Debconf templates do "
1298 "not speak for the Debian developers. You should use neutral construction. "
1299 "Those of you who already wrote scientific publications, just write your "
1300 "templates like you would write a scientific paper. However, try using "
1301 "action voice if still possible, like Enable this if ... instead of This can "
1302 "be enabled if ...."
1305 # type: Content of: <chapter><section><section><section><title>
1306 #: best-pkging-practices.dbk:881
1307 msgid "Be gender neutral"
1310 # type: Content of: <chapter><section><section><section><para>
1311 #: best-pkging-practices.dbk:883
1313 "The world is made of men and women. Please use gender-neutral constructions "
1317 # type: Content of: <chapter><section><section><title>
1318 #: best-pkging-practices.dbk:891
1319 msgid "Templates fields definition"
1322 # type: Content of: <chapter><section><section><para>
1323 #: best-pkging-practices.dbk:893
1325 "This part gives some information which is mostly taken from the "
1326 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1327 "<manvolnum>7</manvolnum> </citerefentry> manual page."
1330 # type: Content of: <chapter><section><section><section><title>
1331 #: best-pkging-practices.dbk:898
1335 # type: Content of: <chapter><section><section><section><section><title>
1336 #: best-pkging-practices.dbk:900
1340 # type: Content of: <chapter><section><section><section><section><para>
1341 #: best-pkging-practices.dbk:902
1342 msgid "Results in a free-form input field that the user can type any string into."
1345 # type: Content of: <chapter><section><section><section><section><title>
1346 #: best-pkging-practices.dbk:907
1350 # type: Content of: <chapter><section><section><section><section><para>
1351 #: best-pkging-practices.dbk:909
1353 "Prompts the user for a password. Use this with caution; be aware that the "
1354 "password the user enters will be written to debconf's database. You should "
1355 "probably clean that value out of the database as soon as is possible."
1358 # type: Content of: <chapter><section><section><section><section><title>
1359 #: best-pkging-practices.dbk:916
1363 # type: Content of: <chapter><section><section><section><section><para>
1364 #: best-pkging-practices.dbk:918
1366 "A true/false choice. Remember: true/false, <emphasis role=\"strong\">not "
1367 "yes/no</emphasis>..."
1370 # type: Content of: <chapter><section><section><section><section><title>
1371 #: best-pkging-practices.dbk:924
1375 # type: Content of: <chapter><section><section><section><section><para>
1376 #: best-pkging-practices.dbk:926
1378 "A choice between one of a number of values. The choices must be specified "
1379 "in a field named 'Choices'. Separate the possible values with commas and "
1380 "spaces, like this: Choices: yes, no, maybe"
1383 # type: Content of: <chapter><section><section><section><section><title>
1384 #: best-pkging-practices.dbk:933
1385 msgid "multiselect:"
1388 # type: Content of: <chapter><section><section><section><section><para>
1389 #: best-pkging-practices.dbk:935
1391 "Like the select data type, except the user can choose any number of items "
1392 "from the choices list (or chose none of them)."
1395 # type: Content of: <chapter><section><section><section><section><title>
1396 #: best-pkging-practices.dbk:941
1400 # type: Content of: <chapter><section><section><section><section><para>
1401 #: best-pkging-practices.dbk:943
1403 "Rather than being a question per se, this datatype indicates a note that can "
1404 "be displayed to the user. It should be used only for important notes that "
1405 "the user really should see, since debconf will go to great pains to make "
1406 "sure the user sees it; halting the install for them to press a key, and even "
1407 "mailing the note to them in some cases."
1410 # type: Content of: <chapter><section><section><section><section><title>
1411 #: best-pkging-practices.dbk:952
1415 # type: Content of: <chapter><section><section><section><section><para>
1416 #: best-pkging-practices.dbk:954
1417 msgid "This type is now considered obsolete: don't use it."
1420 # type: Content of: <chapter><section><section><section><section><title>
1421 #: best-pkging-practices.dbk:959
1425 # type: Content of: <chapter><section><section><section><section><para>
1426 #: best-pkging-practices.dbk:961
1428 "This type is designed to handle error messages. It is mostly similar to the "
1429 "note type. Frontends may present it differently (for instance, the dialog "
1430 "frontend of cdebconf draws a red screen instead of the usual blue one)."
1433 # type: Content of: <chapter><section><section><section><section><para>
1434 #: best-pkging-practices.dbk:966
1436 "It is recommended to use this type for any message that needs user attention "
1437 "for a correction of any kind."
1440 # type: Content of: <chapter><section><section><section><title>
1441 #: best-pkging-practices.dbk:974
1442 msgid "Description: short and extended description"
1445 # type: Content of: <chapter><section><section><section><para>
1446 #: best-pkging-practices.dbk:976
1448 "Template descriptions have two parts: short and extended. The short "
1449 "description is in the Description: line of the template."
1452 # type: Content of: <chapter><section><section><section><para>
1453 #: best-pkging-practices.dbk:980
1455 "The short description should be kept short (50 characters or so) so that it "
1456 "may be accomodated by most debconf interfaces. Keeping it short also helps "
1457 "translators, as usually translations tend to end up being longer than the "
1461 # type: Content of: <chapter><section><section><section><para>
1462 #: best-pkging-practices.dbk:986
1464 "The short description should be able to stand on its own. Some interfaces "
1465 "do not show the long description by default, or only if the user explicitely "
1466 "asks for it or even do not show it at all. Avoid things like What do you "
1470 # type: Content of: <chapter><section><section><section><para>
1471 #: best-pkging-practices.dbk:992
1473 "The short description does not necessarily have to be a full sentence. This "
1474 "is part of the keep it short and efficient recommendation."
1477 # type: Content of: <chapter><section><section><section><para>
1478 #: best-pkging-practices.dbk:996
1480 "The extended description should not repeat the short description word for "
1481 "word. If you can't think up a long description, then first, think some "
1482 "more. Post to debian-devel. Ask for help. Take a writing class! That "
1483 "extended description is important. If after all that you still can't come "
1484 "up with anything, leave it blank."
1487 # type: Content of: <chapter><section><section><section><para>
1488 #: best-pkging-practices.dbk:1003
1490 "The extended description should use complete sentences. Paragraphs should "
1491 "be kept short for improved readability. Do not mix two ideas in the same "
1492 "paragraph but rather use another paragraph."
1495 # type: Content of: <chapter><section><section><section><para>
1496 #: best-pkging-practices.dbk:1008
1498 "Don't be too verbose. User tend to ignore too long screens. 20 lines are "
1499 "by experience a border you shouldn't cross, because that means that in the "
1500 "classical dialog interface, people will need to scroll, and lot of people "
1501 "just don't do that."
1504 # type: Content of: <chapter><section><section><section><para>
1505 #: best-pkging-practices.dbk:1014
1507 "The extended description should <emphasis role=\"strong\">never</emphasis> "
1508 "include a question."
1511 # type: Content of: <chapter><section><section><section><para>
1512 #: best-pkging-practices.dbk:1018
1514 "For specific rules depending on templates type (string, boolean, etc.), "
1515 "please read below."
1518 # type: Content of: <chapter><section><section><section><title>
1519 #: best-pkging-practices.dbk:1024
1523 # type: Content of: <chapter><section><section><section><para>
1524 #: best-pkging-practices.dbk:1026
1526 "This field should be used for Select and Multiselect types. It contains the "
1527 "possible choices which will be presented to users. These choices should be "
1528 "separated by commas."
1531 # type: Content of: <chapter><section><section><section><title>
1532 #: best-pkging-practices.dbk:1033
1536 # type: Content of: <chapter><section><section><section><para>
1537 #: best-pkging-practices.dbk:1035
1539 "This field is optional. It contains the default answer for string, select "
1540 "and multiselect templates. For multiselect templates, it may contain a "
1541 "comma-separated list of choices."
1544 # type: Content of: <chapter><section><section><title>
1545 #: best-pkging-practices.dbk:1044
1546 msgid "Templates fields specific style guide"
1549 # type: Content of: <chapter><section><section><section><title>
1550 #: best-pkging-practices.dbk:1046
1554 # type: Content of: <chapter><section><section><section><para>
1555 #: best-pkging-practices.dbk:1048
1557 "No specific indication except: use the appropriate type by referring to the "
1561 # type: Content of: <chapter><section><section><section><title>
1562 #: best-pkging-practices.dbk:1054
1563 msgid "Description field"
1566 # type: Content of: <chapter><section><section><section><para>
1567 #: best-pkging-practices.dbk:1056
1569 "Below are specific instructions for properly writing the Description (short "
1570 "and extended) depending on the template type."
1573 # type: Content of: <chapter><section><section><section><section><title>
1574 #: best-pkging-practices.dbk:1060
1575 msgid "String/password templates"
1578 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1579 #: best-pkging-practices.dbk:1064
1581 "The short description is a prompt and <emphasis "
1582 "role=\"strong\">not</emphasis> a title. Avoid question style prompts (IP "
1583 "Address?) in favour of opened prompts (IP address:). The use of colons is "
1587 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1588 #: best-pkging-practices.dbk:1071
1590 "The extended description is a complement to the short description. In the "
1591 "extended part, explain what is being asked, rather than ask the same "
1592 "question again using longer words. Use complete sentences. Terse writing "
1593 "style is strongly discouraged."
1596 # type: Content of: <chapter><section><section><section><section><title>
1597 #: best-pkging-practices.dbk:1081
1598 msgid "Boolean templates"
1601 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1602 #: best-pkging-practices.dbk:1085
1604 "The short description should be phrased in the form of a question which "
1605 "should be kept short and should generally end with a question mark. Terse "
1606 "writing style is permitted and even encouraged if the question is rather "
1607 "long (remember that translations are often longer than original versions)"
1610 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1611 #: best-pkging-practices.dbk:1093
1613 "Again, please avoid referring to specific interface widgets. A common "
1614 "mistake for such templates is if you answer Yes-type constructions."
1617 # type: Content of: <chapter><section><section><section><section><title>
1618 #: best-pkging-practices.dbk:1101
1619 msgid "Select/Multiselect"
1622 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1623 #: best-pkging-practices.dbk:1105
1625 "The short description is a prompt and <emphasis "
1626 "role=\"strong\">not</emphasis> a title. Do <emphasis "
1627 "role=\"strong\">not</emphasis> use useless Please choose... constructions. "
1628 "Users are clever enough to figure out they have to choose something...:)"
1631 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1632 #: best-pkging-practices.dbk:1113
1634 "The extended description will complete the short description. It may refer "
1635 "to the available choices. It may also mention that the user may choose more "
1636 "than one of the available choices, if the template is a multiselect one "
1637 "(although the interface often makes this clear)."
1640 # type: Content of: <chapter><section><section><section><section><title>
1641 #: best-pkging-practices.dbk:1123
1645 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1646 #: best-pkging-practices.dbk:1127
1647 msgid "The short description should be considered to be a *title*."
1650 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1651 #: best-pkging-practices.dbk:1132
1653 "The extended description is what will be displayed as a more detailed "
1654 "explanation of the note. Phrases, no terse writing style."
1657 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1658 #: best-pkging-practices.dbk:1138
1660 "<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
1661 "most common way to abuse debconf. As written in debconf-devel manual page: "
1662 "it's best to use them only for warning about very serious problems. The "
1663 "NEWS.Debian or README.Debian files are the appropriate location for a lot of "
1664 "notes. If, by reading this, you consider converting your Note type "
1665 "templates to entries in NEWS/Debian or README.Debian, plus consider keeping "
1666 "existing translations for the future."
1669 # type: Content of: <chapter><section><section><section><title>
1670 #: best-pkging-practices.dbk:1153
1671 msgid "Choices field"
1674 # type: Content of: <chapter><section><section><section><para>
1675 #: best-pkging-practices.dbk:1155
1677 "If the Choices are likely to change often, please consider using the "
1678 "__Choices trick. This will split each individual choice into a single "
1679 "string, which will considerably help translators for doing their work."
1682 # type: Content of: <chapter><section><section><section><title>
1683 #: best-pkging-practices.dbk:1162 best-pkging-practices.dbk:1200
1684 msgid "Default field"
1687 # type: Content of: <chapter><section><section><section><para>
1688 #: best-pkging-practices.dbk:1164
1690 "If the default value, for a select template, is likely to vary depending on "
1691 "the user language (for instance, if the choice is a language choice), please "
1692 "use the _DefaultChoice trick."
1695 # type: Content of: <chapter><section><section><section><para>
1696 #: best-pkging-practices.dbk:1169
1698 "This special field allow translators to put the most appropriate choice "
1699 "according to their own language. It will become the default choice when "
1700 "their language is used while your own mentioned Default Choice will be used "
1701 "chan using English."
1704 # type: Content of: <chapter><section><section><section><para>
1705 #: best-pkging-practices.dbk:1175
1706 msgid "Example, taken from the geneweb package templates:"
1709 # type: Content of: <chapter><section><section><section><screen>
1710 #: best-pkging-practices.dbk:1177
1714 "Template: geneweb/lang\n"
1716 "__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech "
1717 "(cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), "
1718 "Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian "
1719 "(it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian "
1720 "(ro), Russian (ru), Spanish (es), Swedish (sv)\n"
1721 "# This is the default choice. Translators may put their own language here\n"
1722 "# instead of the default.\n"
1723 "# WARNING : you MUST use the ENGLISH FORM of your language\n"
1724 "# For instance, the french translator will need to put French (fr) here.\n"
1725 "_DefaultChoice: English (en)[ translators, please see comment in PO files]\n"
1726 "_Description: Geneweb default language:\n"
1729 # type: Content of: <chapter><section><section><section><para>
1730 #: best-pkging-practices.dbk:1189
1732 "Note the use of brackets which allow internal comments in debconf fields. "
1733 "Also note the use of comments which will show up in files the translators "
1737 # type: Content of: <chapter><section><section><section><para>
1738 #: best-pkging-practices.dbk:1194
1740 "The comments are needed as the DefaultChoice trick is a bit confusing: the "
1741 "translators may put their own choice"
1744 # type: Content of: <chapter><section><section><section><para>
1745 #: best-pkging-practices.dbk:1202
1747 "Do NOT use empty default field. If you don't want to use default values, do "
1748 "not use Default at all."
1751 # type: Content of: <chapter><section><section><section><para>
1752 #: best-pkging-practices.dbk:1206
1754 "If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
1755 "see 2.2), consider making this field translatable, if you think it may be "
1759 # type: Content of: <chapter><section><section><section><para>
1760 #: best-pkging-practices.dbk:1211
1762 "If the default value may vary depending on language/country (for instance "
1763 "the default value for a language choice), consider using the special "
1764 "_DefaultChoice type documented in <citerefentry> "
1765 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1769 # type: Content of: <chapter><section><title>
1770 #: best-pkging-practices.dbk:1223
1771 msgid "Internationalization"
1774 # type: Content of: <chapter><section><section><title>
1775 #: best-pkging-practices.dbk:1225
1776 msgid "Handling debconf translations"
1779 # type: Content of: <chapter><section><section><para>
1780 #: best-pkging-practices.dbk:1227
1782 "Like porters, translators have a difficult task. They work on many packages "
1783 "and must collaborate with many different maintainers. Moreover, most of the "
1784 "time, they are not native English speakers, so you may need to be "
1785 "particularly patient with them."
1788 # type: Content of: <chapter><section><section><para>
1789 #: best-pkging-practices.dbk:1233
1791 "The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
1792 "packages configuration easier for maintainers and for users. Originally, "
1793 "translation of debconf templates was handled with "
1794 "<command>debconf-mergetemplate</command>. However, that technique is now "
1795 "deprecated; the best way to accomplish <systemitem "
1796 "role=\"package\">debconf</systemitem> internationalization is by using the "
1797 "<systemitem role=\"package\">po-debconf</systemitem> package. This method "
1798 "is easier both for maintainer and translators; transition scripts are "
1802 # type: Content of: <chapter><section><section><para>
1803 #: best-pkging-practices.dbk:1243
1805 "Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
1806 "is stored in <filename>po</filename> files (drawing from "
1807 "<command>gettext</command> translation techniques). Special template files "
1808 "contain the original messages and mark which fields are translatable. When "
1809 "you change the value of a translatable field, by calling "
1810 "<command>debconf-updatepo</command>, the translation is marked as needing "
1811 "attention from the translators. Then, at build time, the "
1812 "<command>dh_installdebconf</command> program takes care of all the needed "
1813 "magic to add the template along with the up-to-date translations into the "
1814 "binary packages. Refer to the <citerefentry> "
1815 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1816 "</citerefentry> manual page for details."
1819 # type: Content of: <chapter><section><section><title>
1820 #: best-pkging-practices.dbk:1259
1821 msgid "Internationalized documentation"
1824 # type: Content of: <chapter><section><section><para>
1825 #: best-pkging-practices.dbk:1261
1827 "Internationalizing documentation is crucial for users, but a lot of labor. "
1828 "There's no way to eliminate all that work, but you can make things easier "
1832 # type: Content of: <chapter><section><section><para>
1833 #: best-pkging-practices.dbk:1266
1835 "If you maintain documentation of any size, its easier for translators if "
1836 "they have access to a source control system. That lets translators see the "
1837 "differences between two versions of the documentation, so, for instance, "
1838 "they can see what needs to be retranslated. It is recommended that the "
1839 "translated documentation maintain a note about what source control revision "
1840 "the translation is based on. An interesting system is provided by <ulink "
1841 "url=\"&url-i18n-doc-check;\">doc-check</ulink> in the <systemitem "
1842 "role=\"package\">boot-floppies</systemitem> package, which shows an overview "
1843 "of the translation status for any given language, using structured comments "
1844 "for the current revision of the file to be translated and, for a translated "
1845 "file, the revision of the original file the translation is based on. You "
1846 "might wish to adapt and provide that in your CVS area."
1849 # type: Content of: <chapter><section><section><para>
1850 #: best-pkging-practices.dbk:1280
1852 "If you maintain XML or SGML documentation, we suggest that you isolate any "
1853 "language-independent information and define those as entities in a separate "
1854 "file which is included by all the different translations. This makes it "
1855 "much easier, for instance, to keep URLs up to date across multiple files."
1858 # type: Content of: <chapter><section><title>
1859 #: best-pkging-practices.dbk:1290
1860 msgid "Common packaging situations"
1863 # type: Content of: <chapter><section><section><title>
1864 #: best-pkging-practices.dbk:1301
1865 msgid "Packages using <command>autoconf</command>/<command>automake</command>"
1868 # type: Content of: <chapter><section><section><para>
1869 #: best-pkging-practices.dbk:1303
1871 "Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
1872 "<filename>config.guess</filename> files up to date is critical for porters, "
1873 "especially on more volatile architectures. Some very good packaging "
1874 "practices for any package using <command>autoconf</command> and/or "
1875 "<command>automake</command> have been synthesized in &file-bpp-autotools; "
1876 "from the <systemitem role=\"package\">autotools-dev</systemitem> package. "
1877 "You're strongly encouraged to read this file and to follow the given "
1881 # type: Content of: <chapter><section><section><title>
1882 #: best-pkging-practices.dbk:1315
1886 # type: Content of: <chapter><section><section><para>
1887 #: best-pkging-practices.dbk:1317
1889 "Libraries are always difficult to package for various reasons. The policy "
1890 "imposes many constraints to ease their maintenance and to make sure upgrades "
1891 "are as simple as possible when a new upstream version comes out. Breakage "
1892 "in a library can result in dozens of dependent packages breaking."
1895 # type: Content of: <chapter><section><section><para>
1896 #: best-pkging-practices.dbk:1323
1898 "Good practices for library packaging have been grouped in <ulink "
1899 "url=\"&url-libpkg-guide;\">the library packaging guide</ulink>."
1902 # type: Content of: <chapter><section><section><title>
1903 #: best-pkging-practices.dbk:1330
1904 msgid "Documentation"
1907 # type: Content of: <chapter><section><section><para>
1908 #: best-pkging-practices.dbk:1332
1910 "Be sure to follow the <ulink url=\"&url-debian-policy;ch-docs.html\">Policy "
1911 "on documentation</ulink>."
1914 # type: Content of: <chapter><section><section><para>
1915 #: best-pkging-practices.dbk:1337
1917 "If your package contains documentation built from XML or SGML, we recommend "
1918 "you not ship the XML or SGML source in the binary package(s). If users want "
1919 "the source of the documentation, they should retrieve the source package."
1922 # type: Content of: <chapter><section><section><para>
1923 #: best-pkging-practices.dbk:1342
1925 "Policy specifies that documentation should be shipped in HTML format. We "
1926 "also recommend shipping documentation in PDF and plain text format if "
1927 "convenient and if output of reasonable quality is possible. However, it is "
1928 "generally not appropriate to ship plain text versions of documentation whose "
1929 "source format is HTML."
1932 # type: Content of: <chapter><section><section><para>
1933 #: best-pkging-practices.dbk:1349
1935 "Major shipped manuals should register themselves with <systemitem "
1936 "role=\"package\">doc-base</systemitem> on installation. See the <systemitem "
1937 "role=\"package\">doc-base</systemitem> package documentation for more "
1941 # type: Content of: <chapter><section><section><title>
1942 #: best-pkging-practices.dbk:1357
1943 msgid "Specific types of packages"
1946 # type: Content of: <chapter><section><section><para>
1947 #: best-pkging-practices.dbk:1359
1949 "Several specific types of packages have special sub-policies and "
1950 "corresponding packaging rules and practices:"
1953 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1954 #: best-pkging-practices.dbk:1365
1956 "Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
1957 "policy</ulink>, some examples of packages following that policy are "
1958 "<systemitem role=\"package\">libdbd-pg-perl</systemitem> (binary perl "
1959 "module) or <systemitem role=\"package\">libmldbm-perl</systemitem> (arch "
1960 "independent perl module)."
1963 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1964 #: best-pkging-practices.dbk:1374
1966 "Python related packages have their python policy; see &file-python-policy; "
1967 "in the <systemitem role=\"package\">python</systemitem> package."
1970 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1971 #: best-pkging-practices.dbk:1381
1973 "Emacs related packages have the <ulink url=\"&url-emacs-policy;\">emacs "
1977 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1978 #: best-pkging-practices.dbk:1388
1980 "Java related packages have their <ulink url=\"&url-java-policy;\">java "
1984 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1985 #: best-pkging-practices.dbk:1395
1987 "Ocaml related packages have their own policy, found in &file-ocaml-policy; "
1988 "from the <systemitem role=\"package\">ocaml</systemitem> package. A good "
1989 "example is the <systemitem role=\"package\">camlzip</systemitem> source "
1993 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1994 #: best-pkging-practices.dbk:1403
1996 "Packages providing XML or SGML DTDs should conform to the recommendations "
1997 "found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
2001 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2002 #: best-pkging-practices.dbk:1409
2004 "Lisp packages should register themselves with <systemitem "
2005 "role=\"package\">common-lisp-controller</systemitem>, about which see "
2006 "&file-lisp-controller;."
2009 # type: Content of: <chapter><section><section><title>
2010 #: best-pkging-practices.dbk:1439
2011 msgid "Architecture-independent data"
2014 # type: Content of: <chapter><section><section><para>
2015 #: best-pkging-practices.dbk:1441
2017 "It is not uncommon to have a large amount of architecture-independent data "
2018 "packaged with a program. For example, audio files, a collection of icons, "
2019 "wallpaper patterns, or other graphic files. If the size of this data is "
2020 "negligible compared to the size of the rest of the package, it's probably "
2021 "best to keep it all in a single package."
2024 # type: Content of: <chapter><section><section><para>
2025 #: best-pkging-practices.dbk:1448
2027 "However, if the size of the data is considerable, consider splitting it out "
2028 "into a separate, architecture-independent package (_all.deb). By doing "
2029 "this, you avoid needless duplication of the same data into eleven or more "
2030 ".debs, one per each architecture. While this adds some extra overhead into "
2031 "the <filename>Packages</filename> files, it saves a lot of disk space on "
2032 "Debian mirrors. Separating out architecture-independent data also reduces "
2033 "processing time of <command>lintian</command> (see <xref "
2034 "linkend=\"tools-lint\"/> ) when run over the entire Debian archive."
2037 # type: Content of: <chapter><section><section><title>
2038 #: best-pkging-practices.dbk:1460
2039 msgid "Needing a certain locale during build"
2042 # type: Content of: <chapter><section><section><para>
2043 #: best-pkging-practices.dbk:1462
2045 "If you need a certain locale during build, you can create a temporary file "
2049 # type: Content of: <chapter><section><section><para>
2050 #: best-pkging-practices.dbk:1466
2052 "If you set <varname>LOCPATH</varname> to the equivalent of "
2053 "<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
2054 "name of the locale you generate, you should get what you want without being "
2055 "root. Something like this:"
2058 # type: Content of: <chapter><section><section><screen>
2059 #: best-pkging-practices.dbk:1470
2063 "LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
2064 "LOCALE_NAME=en_IN\n"
2065 "LOCALE_CHARSET=UTF-8\n"
2067 "mkdir -p $LOCALE_PATH\n"
2068 "localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
2069 "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
2071 "# Using the locale\n"
2072 "LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date\n"
2075 # type: Content of: <chapter><section><section><title>
2076 #: best-pkging-practices.dbk:1484
2077 msgid "Make transition packages deborphan compliant"
2080 # type: Content of: <chapter><section><section><para>
2081 #: best-pkging-practices.dbk:1486
2083 "Deborphan is a program for helping users to detect which packages can safely "
2084 "be removed from the system, i.e. the ones that have no packages depending "
2085 "on them. The default operation is to search only within the libs and "
2086 "oldlibs sections, to hunt down unused libraries. But when passed the right "
2087 "argument, it tries to catch other useless packages."
2090 # type: Content of: <chapter><section><section><para>
2091 #: best-pkging-practices.dbk:1493
2093 "For example, with <literal>--guess-dummy</literal>, "
2094 "<command>deborphan</command> tries to search all transitional packages which "
2095 "were needed for upgrade but which can now safely be removed. For that, it "
2096 "looks for the string dummy or transitional in their short description."
2099 # type: Content of: <chapter><section><section><para>
2100 #: best-pkging-practices.dbk:1500
2102 "So, when you are creating such a package, please make sure to add this text "
2103 "to your short description. If you are looking for examples, just run: "
2104 "<command>apt-cache search .|grep dummy</command> or <command>apt-cache "
2105 "search .|grep transitional</command>."
2108 # type: Content of: <chapter><section><section><title>
2109 #: best-pkging-practices.dbk:1508
2110 msgid "Best practices for <filename>orig.tar.gz</filename> files"
2113 # type: Content of: <chapter><section><section><para>
2114 #: best-pkging-practices.dbk:1510
2116 "There are two kinds of original source tarballs: Pristine source and "
2117 "repackaged upstream source."
2120 # type: Content of: <chapter><section><section><section><title>
2121 #: best-pkging-practices.dbk:1514
2122 msgid "Pristine source"
2125 # type: Content of: <chapter><section><section><section><para><footnote>
2126 #: best-pkging-practices.dbk:1516
2128 "The defining characteristic of a pristine source tarball is that the "
2129 "<literal>.orig.tar.gz</literal> file is byte-for-byte identical to a tarball "
2130 "officially distributed by the upstream author. <footnote>"
2133 # type: Content of: <chapter><section><section><section><para><footnote><para>
2134 #: best-pkging-practices.dbk:1518
2136 "We cannot prevent upstream authors from changing the tarball they distribute "
2137 "without also incrementing the version number, so there can be no guarantee "
2138 "that a pristine tarball is identical to what upstream "
2139 "<emphasis>currently</emphasis> distributing at any point in time. All that "
2140 "can be expected is that it is identical to something that upstream once "
2141 "<emphasis>did</emphasis> distribute. If a difference arises later (say, if "
2142 "upstream notices that he wasn't using maximal comression in his original "
2143 "distribution and then re-<command>gzip</command>s it), that's just too bad. "
2144 "Since there is no good way to upload a new <literal>.orig.tar.gz</literal> "
2145 "for the same version, there is not even any point in treating this situation "
2149 # type: Content of: <chapter><section><section><section><para>
2150 #: best-pkging-practices.dbk:1528
2152 "</footnote> This makes it possible to use checksums to easily verify that "
2153 "all changes between Debian's version and upstream's are contained in the "
2154 "Debian diff. Also, if the original source is huge, upstream authors and "
2155 "others who already have the upstream tarball can save download time if they "
2156 "want to inspect your packaging in detail."
2159 # type: Content of: <chapter><section><section><section><para>
2160 #: best-pkging-practices.dbk:1536
2162 "There is no universally accepted guidelines that upstream authors follow "
2163 "regarding to the directory structure inside their tarball, but "
2164 "<command>dpkg-source</command> is nevertheless able to deal with most "
2165 "upstream tarballs as pristine source. Its strategy is equivalent to the "
2169 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2170 #: best-pkging-practices.dbk:1544
2171 msgid "It unpacks the tarball in an empty temporary directory by doing"
2174 # type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
2175 #: best-pkging-practices.dbk:1546
2179 "zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar "
2183 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2184 #: best-pkging-practices.dbk:1552
2186 "If, after this, the temporary directory contains nothing but one directory "
2187 "and no other files, <command>dpkg-source</command> renames that directory to "
2188 "<literal><packagename>-<upstream-version>(.orig)</literal>. The "
2189 "name of the top-level directory in the tarball does not matter, and is "
2193 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2194 #: best-pkging-practices.dbk:1561
2196 "Otherwise, the upstream tarball must have been packaged without a common "
2197 "top-level directory (shame on the upstream author!). In this case, "
2198 "<command>dpkg-source</command> renames the temporary directory "
2199 "<emphasis>itself</emphasis> to "
2200 "<literal><packagename>-<upstream-version>(.orig)</literal>."
2203 # type: Content of: <chapter><section><section><section><title>
2204 #: best-pkging-practices.dbk:1572
2205 msgid "Repackaged upstream source"
2208 # type: Content of: <chapter><section><section><section><para>
2209 #: best-pkging-practices.dbk:1574
2211 "You <emphasis role=\"strong\">should</emphasis> upload packages with a "
2212 "pristine source tarball if possible, but there are various reasons why it "
2213 "might not be possible. This is the case if upstream does not distribute the "
2214 "source as gzipped tar at all, or if upstream's tarball contains "
2215 "non-DFSG-free material that you must remove before uploading."
2218 # type: Content of: <chapter><section><section><section><para>
2219 #: best-pkging-practices.dbk:1581
2221 "In these cases the developer must construct a suitable <literal>.orig.tar.gz "
2222 "</literal> file himself. We refer to such a tarball as a repackaged "
2223 "upstream source. Note that a repackaged upstream source is different from a "
2224 "Debian-native package. A repackaged source still comes with Debian-specific "
2225 "changes in a separate <literal>.diff.gz</literal> and still has a version "
2226 "number composed of <literal><upstream-version></literal> and "
2227 "<literal><debian-revision></literal>."
2230 # type: Content of: <chapter><section><section><section><para>
2231 #: best-pkging-practices.dbk:1590
2233 "There may be cases where it is desirable to repackage the source even though "
2234 "upstream distributes a <literal>.tar.gz</literal> that could in principle be "
2235 "used in its pristine form. The most obvious is if "
2236 "<emphasis>significant</emphasis> space savings can be achieved by "
2237 "recompressing the tar archive or by removing genuinely useless cruft from "
2238 "the upstream archive. Use your own discretion here, but be prepared to "
2239 "defend your decision if you repackage source that could have been pristine."
2242 # type: Content of: <chapter><section><section><section><para>
2243 #: best-pkging-practices.dbk:1599
2244 msgid "A repackaged <literal>.orig.tar.gz</literal>"
2247 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2248 #: best-pkging-practices.dbk:1604
2250 "<emphasis role=\"strong\">must</emphasis> contain detailed information how "
2251 "the repackaged source was obtained, and how this can be reproduced in the "
2252 "<filename>debian/copyright</filename>. It is also a good idea to provide a "
2253 "<literal>get-orig-source</literal> target in your "
2254 "<filename>debian/rules</filename> file that repeats the process, as "
2255 "described in the Policy Manual, <ulink "
2256 "url=\"&url-debian-policy;ch-source.html#s-debianrules\">Main building "
2257 "script: debian/rules</ulink>."
2260 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote>
2261 #: best-pkging-practices.dbk:1616
2263 "<emphasis role=\"strong\">should not</emphasis> contain any file that does "
2264 "not come from the upstream author(s), or whose contents has been changed by "
2268 #. or similarly named
2269 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
2270 #: best-pkging-practices.dbk:1618
2272 "As a special exception, if the omission of non-free files would lead to the "
2273 "source failing to build without assistance from the Debian diff, it might be "
2274 "appropriate to instead edit the files, omitting only the non-free parts of "
2275 "them, and/or explain the situation in a README.Debian-source file in the "
2276 "root of the source tree. But in that case please also urge the upstream "
2277 "author to make the non-free components easier seperable from the rest of the "
2281 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2282 #: best-pkging-practices.dbk:1625
2286 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2287 #: best-pkging-practices.dbk:1630
2289 "<emphasis role=\"strong\">should</emphasis>, except where impossible for "
2290 "legal reasons, preserve the entire building and portablility infrastructure "
2291 "provided by the upstream author. For example, it is not a sufficient reason "
2292 "for omitting a file that it is used only when building on MS-DOS. "
2293 "Similarly, a Makefile provided by upstream should not be omitted even if the "
2294 "first thing your <filename>debian/rules</filename> does is to overwrite it "
2295 "by running a configure script."
2298 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2299 #: best-pkging-practices.dbk:1639
2301 "(<emphasis>Rationale:</emphasis> It is common for Debian users who need to "
2302 "build software for non-Debian platforms to fetch the source from a Debian "
2303 "mirror rather than trying to locate a canonical upstream distribution "
2307 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2308 #: best-pkging-practices.dbk:1646
2310 "<emphasis role=\"strong\">should</emphasis> use "
2311 "<literal><packagename>-<upstream-version>.orig</literal> as the "
2312 "name of the top-level directory in its tarball. This makes it possible to "
2313 "distinguish pristine tarballs from repackaged ones."
2316 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2317 #: best-pkging-practices.dbk:1654
2319 "<emphasis role=\"strong\">should</emphasis> be gzipped with maximal "
2323 # type: Content of: <chapter><section><section><section><para>
2324 #: best-pkging-practices.dbk:1659
2326 "The canonical way to meet the latter two points is to let "
2327 "<literal>dpkg-source -b</literal> construct the repackaged tarball from an "
2328 "unpacked directory."
2331 # type: Content of: <chapter><section><section><section><title>
2332 #: best-pkging-practices.dbk:1665
2333 msgid "Changing binary files in <literal>diff.gz</literal>"
2336 # type: Content of: <chapter><section><section><section><para><footnote>
2337 #: best-pkging-practices.dbk:1667
2339 "Sometimes it is necessary to change binary files contained in the original "
2340 "tarball, or to add binary files that are not in it. If this is done by "
2341 "simply copying the files into the debianized source tree, "
2342 "<command>dpkg-source</command> will not be able to handle this. On the "
2343 "other hand, according to the guidelines given above, you cannot include such "
2344 "a changed binary file in a repackaged <filename>orig.tar.gz</filename>. "
2345 "Instead, include the file in the <filename>debian</filename> directory in "
2346 "<command>uuencode</command>d (or similar) form <footnote>"
2349 # type: Content of: <chapter><section><section><section><para><footnote><para>
2350 #: best-pkging-practices.dbk:1674
2352 "The file should have a name that makes it clear which binary file it "
2353 "encodes. Usually, some postfix indicating the encoding should be appended "
2354 "to the original filename. Note that you don't need to depend on <systemitem "
2355 "role=\"package\">sharutils</systemitem> to get the "
2356 "<command>uudecode</command> program if you use <command>perl</command>'s "
2357 "<literal>pack</literal> function. The code could look like"
2360 # type: Content of: <chapter><section><section><section><para>
2361 #: best-pkging-practices.dbk:1682
2363 "&example-uu; </footnote>. The file would then be decoded and copied to its "
2364 "place during the build process. Thus the change will be visible quite easy."
2367 # type: Content of: <chapter><section><section><section><para>
2368 #: best-pkging-practices.dbk:1688
2370 "Some packages use <command>dbs</command> to manage patches to their upstream "
2371 "source, and always create a new <literal>orig.tar.gz</literal> file that "
2372 "contains the real <literal>orig.tar.gz</literal> in its toplevel directory. "
2373 "This is questionable with respect to the preference for pristine source. On "
2374 "the other hand, it is easy to modify or add binary files in this case: Just "
2375 "put them into the newly created <literal>orig.tar.gz</literal> file, besides "
2376 "the real one, and copy them to the right place during the build process."
2379 # type: Content of: <chapter><section><section><title>
2380 #: best-pkging-practices.dbk:1701
2381 msgid "Best practices for debug packages"
2384 # type: Content of: <chapter><section><section><para>
2385 #: best-pkging-practices.dbk:1703
2387 "A debug package is a package with a name ending in -dbg, that contains "
2388 "additional information that gdb can use. Since Debian binaries are stripped "
2389 "by default, debugging information, including function names and line "
2390 "numbers, is otherwise not available when running gdb on Debian binaries. "
2391 "Debug packages allow users who need this additional debugging information to "
2392 "install it, without bloating a regular system with the information."
2395 # type: Content of: <chapter><section><section><para>
2396 #: best-pkging-practices.dbk:1711
2398 "It is up to a package's maintainer whether to create a debug package or "
2399 "not. Maintainers are encouraged to create debug packages for library "
2400 "packages, since this can aid in debugging many programs linked to a "
2401 "library. In general, debug packages do not need to be added for all "
2402 "programs; doing so would bloat the archive. But if a maintainer finds that "
2403 "users often need a debugging version of a program, it can be worthwhile to "
2404 "make a debug package for it. Programs that are core infrastructure, such as "
2405 "apache and the X server are also good candidates for debug packages."
2408 # type: Content of: <chapter><section><section><para>
2409 #: best-pkging-practices.dbk:1721
2411 "Some debug packages may contain an entire special debugging build of a "
2412 "library or other binary, but most of them can save space and build time by "
2413 "instead containing separated debugging symbols that gdb can find and load on "
2414 "the fly when debugging a program or library. The convention in Debian is to "
2415 "keep these symbols in "
2416 "<filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where "
2417 "<replaceable>path</replaceable> is the path to the executable or library. "
2418 "For example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
2419 "<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for "
2420 "<filename>/usr/lib/libfoo.so.1</filename> go in "
2421 "<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>."
2424 # type: Content of: <chapter><section><section><para>
2425 #: best-pkging-practices.dbk:1733
2427 "The debugging symbols can be extracted from an object file using <command> "
2428 "objcopy --only-keep-debug</command>. Then the object file can be stripped, "
2429 "and <command>objcopy --add-gnu-debuglink</command> used to specify the path "
2430 "to the debugging symbol file. <citerefentry> "
2431 "<refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum> "
2432 "</citerefentry> explains in detail how this works."
2435 # type: Content of: <chapter><section><section><para>
2436 #: best-pkging-practices.dbk:1741
2438 "The <command>dh_strip</command> command in debhelper supports creating debug "
2439 "packages, and can take care of using <command>objcopy</command> to separate "
2440 "out the debugging symbols for you. If your package uses debhelper, all you "
2441 "need to do is call <command>dh_strip --dbg-package=libfoo-dbg</command>, and "
2442 "add an entry to <filename>debian/control</filename> for the debug package."
2445 # type: Content of: <chapter><section><section><para>
2446 #: best-pkging-practices.dbk:1748
2448 "Note that the Debian package should depend on the package that it provides "
2449 "debugging symbols for, and this dependency should be versioned. For "
2453 # type: Content of: <chapter><section><section><screen>
2454 #: best-pkging-practices.dbk:1751
2458 "Depends: libfoo-dbg (= ${binary:Version})\n"