Drop section on debsums as this functionality is now integrated in dpkg. Closes:...

[developers-reference.git] / best-pkging-practices.dbk

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 8b03c4771eeabd5950f8cb180f4ce88d0001df11..1651ddba158761370bb4f00ab639dd1f9c327542 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -75,13 +75,6 @@ individual <command>dh_*</command> helpers.  If you are going to use a helper,
 you do need to take the time to learn to use that helper, to learn its
 expectations and behavior.
 </para>
 you do need to take the time to learn to use that helper, to learn its
 expectations and behavior.
 </para>

-<para>
-Some people feel that vanilla <filename>debian/rules</filename> files are
-better, since you don't have to learn the intricacies of any helper system.
-This decision is completely up to you.  Use what works for you.  Many examples
-of vanilla <filename>debian/rules</filename> files are available at <ulink
-url="&url-rules-files;"></ulink>.
-</para>

 </section>
 
 <section id="multiple-patches">
 </section>
 
 <section id="multiple-patches">


@@ -414,7 +407,7 @@ described above is also shown.
   Priority: optional
   &lt;snip&gt;
   Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
   Priority: optional
   &lt;snip&gt;
   Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim

-  Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
+  Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim

   Homepage: http://www.vim.org
 </screen>
 </section>
   Homepage: http://www.vim.org
 </screen>
 </section>


@@ -830,128 +823,62 @@ If you don't do so, the whole template will not be translated as long as a
 translator will send you an update.
 </para>
 <para>
 translator will send you an update.
 </para>
 <para>

-To <emphasis>unfuzzy</emphasis> translations, you can use two methods. The first
-method does <emphasis>preventive</emphasis> search and replace actions in the
-PO files. The latter uses <command>gettext</command> utilities to <emphasis>unfuzzy</emphasis>
-strings.
-</para>
-<para>
-<emphasis>Preventive unfuzzy</emphasis> method:
+To <emphasis>unfuzzy</emphasis> translations, you can use
+<command>msguntypot</command> (part of the <systemitem
+role="package">po4a</systemitem> package).

 </para>
 <orderedlist numeration="arabic">
 <listitem>
 <para>
 </para>
 <orderedlist numeration="arabic">
 <listitem>
 <para>

-Try finding a complete translation file <emphasis role="strong">before</emphasis>
-the change:
-</para>
-<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done</programlisting>
-<para>
-The file only showing <emphasis>translated</emphasis> items will be used
-as the reference file. If there is none (which should not happen if you take
-care to properly interact with translators), you should use the file
-with the most translated strings.
-</para>
-</listitem>
-<listitem>
-<para>
-Identify the needed change. In this example, let's assume the change is about
-fixing a typo in the word <literal>typo</literal> which was inadvertently
-written as <literal>tpyo</literal>. Therefore, the change is
-<command>s/tpyo/typo</command>.
-</para>
-</listitem>
-<listitem>
-<para>
-Check that this change is only applied to the place where you really intend
-to make it and <emphasis role="strong">not</emphasis> in any other place
-where the original string is appropriate. This specifically applies to
-change in punctuation, for instance.
-</para>
-</listitem>
-<listitem>
-<para>
-Modify all PO files by using <command>sed</command>. The use of that command
-is recommended over any text editor to guarantee that the files encoding will
-not be broken by the edit action:
-</para>
-<programlisting>
-cd debian/po
-for i in *.po; do sed -i 's/tpyo/typo/g' $i; done
-</programlisting>
-</listitem>
-<listitem>
-<para>
-Change the debconf template file to fix the typo.
-</para>
-</listitem>
-<listitem>
-<para>
-Run <command>debconf-updatepo</command>.
-</para>
-</listitem>
-<listitem>
-<para>
-Check the <filename>foo.po</filename> reference file. Its statistics should
-not be changed:
+Regenerate the POT and PO files.

 </para>
 </para>

-<programlisting>
-msgfmt -o /dev/null --statistics debian/po/foo.po
-</programlisting>
+<programlisting>debconf-updatepo</programlisting>

 </listitem>
 <listitem>
 <para>
 </listitem>
 <listitem>
 <para>

-If the file's statistics changed, you did something wrong. Try again
-or ask for help on the &email-debian-i18n; mailing list.
+Make a copy of the POT file.

 </para>
 </para>

+<programlisting>cp templates.pot templates.pot.orig</programlisting>

 </listitem>
 </listitem>

-</orderedlist>
-<para>
-Gettext utilities method:
-</para>
-<orderedlist numeration="arabic">

 <listitem>
 <para>
 <listitem>
 <para>

-Put all incomplete PO files out of the way.  You can check the completeness by
-using (needs the <systemitem role="package">gettext</systemitem> package
-installed):
+Make a copy of all the PO files.

 </para>
 </para>

-<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done</programlisting>
+<programlisting>mkdir po_fridge; cp *.po po_fridge</programlisting>

 </listitem>
 <listitem>
 <para>
 </listitem>
 <listitem>
 <para>

-Move all files which report either fuzzy strings to a temporary place.  Files
-which report no fuzzy strings (only translated and untranslated) will be kept
-in place.
+Change the debconf template files to fix the typos.

 </para>
 </listitem>
 <listitem>
 <para>
 </para>
 </listitem>
 <listitem>
 <para>

-Now <emphasis role="strong">and now only</emphasis>, modify the template for
-the typos and check again that translation are not impacted (typos, spelling
-errors, sometimes typographical corrections are usually OK).
+Regenerate the POT and PO files (again).

 </para>
 </para>

-</listitem>
-<listitem>
+<programlisting>debconf-updatepo</programlisting>

 <para>
 <para>

-Run <command>debconf-updatepo</command>.  This will fuzzy all strings you
-modified in translations.  You can see this by running the above again.
+At this point, the typo fix fuzzied all the translations, and this
+unfortunate change is the only one between the PO files of your main
+directory and the one from the fridge. Here is how to solve this.

 </para>
 </listitem>
 <listitem>
 <para>
 </para>
 </listitem>
 <listitem>
 <para>

-Use the following command:
+Discard fuzzy translation, restore the ones from the fridge.

 </para>
 </para>

-<programlisting>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</programlisting>
+<programlisting>cp po_fridge/*.po .</programlisting>

 </listitem>
 <listitem>
 <para>
 </listitem>
 <listitem>
 <para>

-Move back to <filename>debian/po</filename> the files which showed fuzzy strings in the first step.
+Manually merge the PO files with the new POT file, but taking the useless fuzzy into account.

 </para>
 </para>

+<programlisting>msguntypot -o templates.pot.orig -n templates.pot *.po</programlisting>

 </listitem>
 <listitem>
 <para>
 </listitem>
 <listitem>
 <para>

-Run <command>debconf-updatepo</command> again.
+Clean up.

 </para>
 </para>

+<programlisting>rm -rf templates.pot.orig po_fridge</programlisting>

 </listitem>
 </orderedlist>
 </section>
 </listitem>
 </orderedlist>
 </section>


@@ -1362,7 +1289,7 @@ type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
 <title>Internationalization</title>
 <para>
 This section contains global information for developers to make translators'
 <title>Internationalization</title>
 <para>
 This section contains global information for developers to make translators'

-life easier.  More information for translators and developers interrested
+life easier.  More information for translators and developers interested

 in internationalization are available in the <ulink
 url="&url-i18n-l10n;">Internationalisation and localisation in Debian</ulink>
 documentation.
 in internationalization are available in the <ulink
 url="&url-i18n-l10n;">Internationalisation and localisation in Debian</ulink>
 documentation.


@@ -1680,7 +1607,7 @@ in order to ease <command>deborphan</command>'s job.
 </section>
 
 <section id="bpp-origtargz">
 </section>
 
 <section id="bpp-origtargz">

-<title>Best practices for <filename>.orig.tar.{gz,bz2,lzma}</filename> files</title>
+<title>Best practices for <filename>.orig.tar.{gz,bz2,xz}</filename> files</title>

 <para>
 There are two kinds of original source tarballs: Pristine source and repackaged
 upstream source.
 <para>
 There are two kinds of original source tarballs: Pristine source and repackaged
 upstream source.


@@ -1689,17 +1616,17 @@ upstream source.
 <title>Pristine source</title>
 <para>
 The defining characteristic of a pristine source tarball is that the
 <title>Pristine source</title>
 <para>
 The defining characteristic of a pristine source tarball is that the

-<filename>.orig.tar.{gz,bz2,lzma}</filename> file is byte-for-byte identical to a tarball officially
+<filename>.orig.tar.{gz,bz2,xz}</filename> file is byte-for-byte identical to a tarball officially

 distributed by the upstream author.<footnote><para> We cannot prevent
 upstream authors from changing the tarball they distribute without also
 incrementing the version number, so there can be no guarantee that a pristine
 tarball is identical to what upstream <emphasis>currently</emphasis>
 distributing at any point in time.  All that can be expected is that it is
 identical to something that upstream once <emphasis>did</emphasis> distribute.
 distributed by the upstream author.<footnote><para> We cannot prevent
 upstream authors from changing the tarball they distribute without also
 incrementing the version number, so there can be no guarantee that a pristine
 tarball is identical to what upstream <emphasis>currently</emphasis>
 distributing at any point in time.  All that can be expected is that it is
 identical to something that upstream once <emphasis>did</emphasis> distribute.

-If a difference arises later (say, if upstream notices that he wasn't using
-maximal compression in his original distribution and then
-re-<command>gzip</command>s it), that's just too bad.  Since there is no good
-way to upload a new <filename>.orig.tar.{gz,bz2,lzma}</filename> for the same version, there is not even any
+If a difference arises later (say, if upstream notice that they weren't using
+maximal compression in their original distribution and then
+re-<command>gzip</command> it), that's just too bad.  Since there is no good
+way to upload a new <filename>.orig.tar.{gz,bz2,xz}</filename> for the same version, there is not even any

 point in treating this situation as a bug.  </para> </footnote> This makes it
 possible to use checksums to easily verify that all changes between Debian's
 version and upstream's are contained in the Debian diff.  Also, if the original
 point in treating this situation as a bug.  </para> </footnote> This makes it
 possible to use checksums to easily verify that all changes between Debian's
 version and upstream's are contained in the Debian diff.  Also, if the original


@@ -1753,17 +1680,17 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
 that you must remove before uploading.
 </para>
 <para>
 that you must remove before uploading.
 </para>
 <para>

-In these cases the developer must construct a suitable <filename>.orig.tar.{gz,bz2,lzma}</filename>
-file himself.  We refer to such a tarball as a repackaged upstream 
+In these cases the developer must construct a suitable <filename>.orig.tar.{gz,bz2,xz}</filename>
+file themselves.  We refer to such a tarball as a repackaged upstream

 source.  Note that a repackaged upstream source is different from a 
 Debian-native package.  A repackaged source still comes with Debian-specific
 source.  Note that a repackaged upstream source is different from a 
 Debian-native package.  A repackaged source still comes with Debian-specific

-changes in a separate <filename>.diff.gz</filename> or <filename>.debian.tar.{gz,bz2,lzma}</filename>
+changes in a separate <filename>.diff.gz</filename> or <filename>.debian.tar.{gz,bz2,xz}</filename>

 and still has a version number composed of <replaceable>upstream-version</replaceable> and
 <replaceable>debian-version</replaceable>.
 </para>
 <para>
 There may be cases where it is desirable to repackage the source even though
 and still has a version number composed of <replaceable>upstream-version</replaceable> and
 <replaceable>debian-version</replaceable>.
 </para>
 <para>
 There may be cases where it is desirable to repackage the source even though

-upstream distributes a <filename>.tar.{gz,bz2,lzma}</filename> that could in principle be
+upstream distributes a <filename>.tar.{gz,bz2,xz}</filename> that could in principle be

 used in its pristine form.  The most obvious is if
 <emphasis>significant</emphasis> space savings can be achieved by recompressing
 the tar archive or by removing genuinely useless cruft from the upstream
 used in its pristine form.  The most obvious is if
 <emphasis>significant</emphasis> space savings can be achieved by recompressing
 the tar archive or by removing genuinely useless cruft from the upstream


@@ -1771,7 +1698,7 @@ archive.  Use your own discretion here, but be prepared to defend your decision
 if you repackage source that could have been pristine.
 </para>
 <para>
 if you repackage source that could have been pristine.
 </para>
 <para>

-A repackaged <filename>.orig.tar.{gz,bz2,lzma}</filename>
+A repackaged <filename>.orig.tar.{gz,bz2,xz}</filename>

 </para>
 <orderedlist numeration="arabic">
 <listitem>
 </para>
 <orderedlist numeration="arabic">
 <listitem>


@@ -1912,17 +1839,17 @@ coherent set of packages that can evolve over time. It achieves this by
 depending on all the packages of the set. Thanks to the power of APT, the
 meta-package maintainer can adjust the dependencies and the user's system
 will automatically get the supplementary packages. The dropped packages
 depending on all the packages of the set. Thanks to the power of APT, the
 meta-package maintainer can adjust the dependencies and the user's system
 will automatically get the supplementary packages. The dropped packages

-that were automaticaly installed will be also be marked as removal
+that were automatically installed will be also be marked as removal

 candidates (and are even automatically removed by <command>aptitude</command>).
 <systemitem role="package">gnome</systemitem> and
 <systemitem role="package">linux-image-amd64</systemitem> are two examples
 of meta-packages (built by the source packages
 <systemitem role="package">meta-gnome2</systemitem> and
 candidates (and are even automatically removed by <command>aptitude</command>).
 <systemitem role="package">gnome</systemitem> and
 <systemitem role="package">linux-image-amd64</systemitem> are two examples
 of meta-packages (built by the source packages
 <systemitem role="package">meta-gnome2</systemitem> and

-<systemitem role="package">linux-latest</systemitem>)
+<systemitem role="package">linux-latest</systemitem>).

 </para>
 <para>
 The long description of the meta-package must clearly document its purpose
 </para>
 <para>
 The long description of the meta-package must clearly document its purpose

-so that the user knows what he will lose if he removes the package. Being
+so that the user knows what they will lose if they remove the package. Being

 explicit about the consequences is recommended. This is particularly
 important for meta-packages which are installed during initial
 installation and that have not been explicitly installed by the user.
 explicit about the consequences is recommended. This is particularly
 important for meta-packages which are installed during initial
 installation and that have not been explicitly installed by the user.