<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.255 $">
+ <!ENTITY cvs-rev "$Revision: 1.258 $">
<!-- if you are translating this document, please notate the CVS
revision of the original developer's reference in cvs-en-rev -->
<copyright>
<copyrightsummary>
-copyright © 2004 Andreas Barth</copyrightsummary>
+copyright © 2004—2005 Andreas Barth</copyrightsummary>
<copyrightsummary>
copyright © 1998—2003 Adam Di Carlo</copyrightsummary>
<copyrightsummary>
person to get your key signed. There's a <url id="&url-gpg-coord;"
name="GnuPG Key Signing Coordination page"> which should help you find
a maintainer close to you. (If you cannot find a Debian maintainer
-close to you, there's an alternative way to pass the ID check. You
-can send in a photo ID signed with your GnuPG key. Having your GnuPG
-key signed is the preferred way, however. See the
-<url id="&url-newmaint-id;" name="identification page"> for more
-information about these two options.)
+close to you, there may be alternative ways to pass the ID check.
+See the <url id="&url-newmaint-id;" name="identification page">
+for more informations.)
<p>
If you do not have an OpenPGP key yet, generate one. Every developer
OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
2440">.
<p>
-<!-- FIXME: DSS is not exactly equivalent to DSA, is it? -->
-The recommended public key algorithm for use in Debian development
-work is DSA (sometimes called ``DSS'' or ``DH/ElGamal'').
-Other key types may be used, however. Your key length must be at least 1024
+You need a type 4 key for use in Debian Development.
+Your key length must be at least 1024
bits; there is no reason to use a smaller key, and doing so would be
-much less secure. Your key must be signed with at least your own user
+much less secure. Your key must be signed with your own user
ID; this prevents user ID tampering. <prgn>gpg</prgn> does this
automatically.
<p>
</example>
Once you've made that change, <prgn>dupload</prgn> can be used to
easily upload a package in one of the delayed directories:
-<example>DELAY=5 dupload --to delayed <changes-file></example>
+<example>DELAY=5 dupload -X-to delayed <changes-file></example>
-->
to the Bug Tracking System. Maintainers almost always appreciate
quality patches and bug reports.
+ <sect1 id="nmu-katie">How dak detects NMUs
+ <p>
+Whether an upload is treated as an NMU or as a maintainer upload by
+the archive scripts and the bugtracking system (see <ref
+id="nmu-patch">) is <em>not</em> decided by looking at the version
+number (see <ref id="nmu-version">). Instead, an upload is handled as
+an NMU if the maintainer address in the <tt>.changes</tt> file is not
+binary the same as the address in the <tt>Maintainer</tt> field, or
+any of the addresses the <tt>Uploaders</tt> field, of the <tt>dsc</tt>
+file, and also if the maintainer address is not special (i.e. it is
+not set to the QA Group address).
+
<sect1 id="nmu-terms">Terminology
<p>
There are two new terms used throughout this section: ``binary-only NMU''
from Debian developers. Feel free to pick and choose whatever works
best for you.
- <sect id="bpp-origtargz">
- <heading>Best practices for <file>orig.tar.gz</file> files</heading>
- <p>
- There are two kinds of original source tarballs: Pristine source
- and repackaged upstream source.
- </p>
- <sect1 id="pristine source">
- <heading>Pristine source</heading>
- <p>
-The defining characteristic of a pristine source tarball is that the
-.orig.tar.gz file is byte-for-byte identical to a tarball officially
-distributed by the upstream author.
-<footnote>
-We cannot prevent upstream authors from changing the tarball
-they distribute without also upping the version number, so
-there can be no guarantee that a pristine tarball is identical
-to what upstream <em>currently</em> distributing at any point in
-time. All that can be expected is that it is identical to
-something that upstream once <em>did</em> distribute.
-
-If a difference arises later (say, if upstream notices that he wasn't
-using maximal comression in his original distribution and then
-re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way
-to upload a new .orig.tar.gz for the same version, there is not even
-any point in treating this situation as a bug.
-</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 source is huge, upstream authors
-and others who already have the upstream tarball can save download
-time if they want to inspect your packaging in detail.
- </p>
- <p>
-There is no universally accepted guidelines that upstream authors
-follow regarding to the directory structure inside their tarball, but
-<prgn>dpkg-source</prgn> is nevertheless able to deal with most
-upstream tarballs as pristine source. Its strategy is equivalent to
-the following:
- </p>
- <p>
- <enumlist>
- <item>
-It unpacks the tarball in an empty temporary directory by doing
-
-<example>
-zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - +</example>
- </item>
- <item>
-If, after this, the temporary directory contains nothing but one
-directory and no other files, <prgn>dpkg-source</prgn> renames that
-directory to
-<tt><packagename>-<upstream-version>(.orig)</tt>. The name
-of the top-level directory in the tarball does not matter, and is
-forgotten.
- </item>
- <item>
-Otherwise, the upstream tarball must have been packaged without a
-common top-level directory (shame on the upstream author!). In this
-case, <prgn>dpkg-source</prgn> renames the temporary directory
-<em>itself</em> to
-<tt><packagename>-<upstream-version>(.orig)</tt>.
- </item>
- </enumlist>
- </p>
- </sect1>
- <sect1 id="repackaged origtargz">
- <heading>Repackaged upstream source</heading>
- <p>
-You <strong>should</strong> upload packages with a pristine source
-tarball if possible, but there are various reasons why it might not be
-possible. This is the case if upstream does not distribute the source
-as gzipped tar at all, or if upstream's tarball contains non-DFSG-free
-material that you must remove before uploading.
- </p>
- <p>
-In these cases the developer must construct a suitable .orig.tar.gz
-file himself. 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 changes in a separate <tt>.diff.gz</tt> and still has
-a version number composed of <tt><upstream-version></tt> and
-<tt><debian-revision></tt>.
- </p>
- <p>
-There may be cases where it is desirable to repackage the source even
-though upstream distributes a <tt>.tar.gz</tt> that could in principle
-be used in its pristine form. The most obvious is if
-<em>significant</em> space savings can be achieved by recompressing
-the tar archive or by removing genuinely useless cruft from the
-upstream archive. Use your own discretion here, but be prepared to
-defend your decision if you repackage source that could have been
-pristine.
- </p>
- <p>
-A repackaged .orig.tar.gz
- </p> + <p>
- <enumlist>
- <item>
-<p>
-<strong>must</strong> contain detailed information how
-the repackaged source was obtained, and how this can be reproduced, in
-<file>README.Debian-source</file> or a similar file. This file should
-be in the <file>diff.gz</file> part of the Debian source package,
-usually in the <file>debian</file> directory, <em>not</em> in the
-repackaged <file>orig.tar.gz</file>. It is also a good idea to provide a
-<tt>get-orig-source</tt> target in your <file>debian/rules</file> file
-that repeats the process, as described in the Policy Manual, <url
-id="&url-debian-policy;ch-source.html#s-debianrules" name="Main
-building script: debian/rules">.
-</p>
- </item>
- <item>
-<strong>should not</strong> contain any file that does not come from the
-upstream author(s), or whose contents has been changed by you.
-<footnote>
-As a special exception, if the omission of non-free files would lead
-to the source failing to build without assistance from the Debian
-diff, it might be appropriate to instead edit the files, omitting only
-the non-free parts of them, and/or explain the situation in a
-README.Debian-source <!-- or similarly named --> file in the root of the source
-tree. But in that case please also urge the upstream author to make
-the non-free components easier seperable from the rest of the source.
-</footnote>
- </item>
- <item>
-<p>
-<strong>should</strong>, except where impossible for legal reasons,
-preserve the entire building and portablility infrastructure provided
-by the upstream author. For example, it is not a sufficient reason for
-omitting a file that it is used only when building on
-MS-DOS. Similarly, a Makefile provided by upstream should not be
-omitted even if the first thing your <file>debian/rules</file> does is
-to overwrite it by running a configure script.
-</p>
-<p>
-(<em>Rationale:</em> It is common for Debian users who need to build
-software for non-Debian platforms to fetch the source from a Debian
-mirror rather than trying to locate a canonical upstream distribution
-point).
-</p> </item>
- <item>
-<strong>should</strong> use
-<tt><packagename>-<upstream-version>.orig</tt> as the name
-of the top-level directory in its tarball. This makes it possible to
-distinguish pristine tarballs from repackaged ones. + </item>
- <item>
-<strong>should</strong> be gzipped with maximal compression.
- </item>
- </enumlist>
- </p>
- <p>
-The canonical way to meet the latter two points is to let
-<tt>dpkg-source -b</tt> construct the repackaged tarball from an
-unpacked directory.
- </p>
- </sect1>
- <sect1 id="changed-binfiles">
- <heading>Changing binary files in <tt>diff.gz</tt></heading>
- <p>
-Sometimes it is necessary to change binary files contained in the
-original tarball, or to add binary files that are not in it.
-If this is done by simply copying the files into the debianized source
-tree, <prgn>dpkg-source</prgn> will not be able to handle this. On the
-other hand, according to the guidelines given above, you cannot
-include such a changed binary file in a repackaged
-<file>orig.tar.gz</file>. Instead, include the file in the
-<file>debian</file> directory in <prgn>uuencode</prgn>d (or similar)
-form
-<footnote>
-The file should have a name that makes it clear which binary file it
-encodes. Usually, some postfix indicating the encoding should be
-appended to the original filename.
-</footnote>.
-The file would then be decoded and copied to its place during the
-build process. Thus the change will be visible quite easy.
-</p>
-<p>
-Some packages use <prgn>dbs</prgn> to manage patches to their upstream
-source, and always create a new <tt>orig.tar.gz</tt> file that
-contains the real <tt>orig.tar.gz</tt> in its toplevel directory. This
-is questionable with respect to the preference for pristine source. On
-the other hand, it is easy to modify or add binary files in this case:
-Just put them into the newly created <tt>orig.tar.gz</tt> file,
-besides the real one, and copy them to the right place during the
-build process.
- </p>
- </sect1>
- </sect>
-
<sect id="bpp-debian-rules">
<heading>Best practices for <file>debian/rules</file></heading>
<p>
either to provide several flavors of the same software (e.g.,
the <package>vim</package> source package) or to make several small
packages instead of a big one (e.g., if the user can install only the
-subset she needs, and thus save some disk space).
+subset needed, and thus save some disk space).
<p>
The second case can be easily managed in <file>debian/rules</file>.
You just need to move the appropriate files from the build directory
<example>apt-cache search .|grep transitional</example>.
</sect1>
+
+ <sect1 id="bpp-origtargz">
+ <heading>Best practices for <file>orig.tar.gz</file> files</heading>
+ <p>
+ There are two kinds of original source tarballs: Pristine source
+ and repackaged upstream source.
+ </p>
+ <sect2 id="pristine source">
+ <heading>Pristine source</heading>
+ <p>
+The defining characteristic of a pristine source tarball is that the
+.orig.tar.gz file is byte-for-byte identical to a tarball officially
+distributed by the upstream author.
+<footnote>
+We cannot prevent upstream authors from changing the tarball
+they distribute without also upping the version number, so
+there can be no guarantee that a pristine tarball is identical
+to what upstream <em>currently</em> distributing at any point in
+time. All that can be expected is that it is identical to
+something that upstream once <em>did</em> distribute.
+
+If a difference arises later (say, if upstream notices that he wasn't
+using maximal comression in his original distribution and then
+re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way
+to upload a new .orig.tar.gz for the same version, there is not even
+any point in treating this situation as a bug.
+</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 source is huge, upstream authors
+and others who already have the upstream tarball can save download
+time if they want to inspect your packaging in detail.
+ </p>
+ <p>
+There is no universally accepted guidelines that upstream authors
+follow regarding to the directory structure inside their tarball, but
+<prgn>dpkg-source</prgn> is nevertheless able to deal with most
+upstream tarballs as pristine source. Its strategy is equivalent to
+the following:
+ </p>
+ <p>
+ <enumlist>
+ <item>
+It unpacks the tarball in an empty temporary directory by doing
+
+<example>
+zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - +</example>
+ </item>
+ <item>
+If, after this, the temporary directory contains nothing but one
+directory and no other files, <prgn>dpkg-source</prgn> renames that
+directory to
+<tt><packagename>-<upstream-version>(.orig)</tt>. The name
+of the top-level directory in the tarball does not matter, and is
+forgotten.
+ </item>
+ <item>
+Otherwise, the upstream tarball must have been packaged without a
+common top-level directory (shame on the upstream author!). In this
+case, <prgn>dpkg-source</prgn> renames the temporary directory
+<em>itself</em> to
+<tt><packagename>-<upstream-version>(.orig)</tt>.
+ </item>
+ </enumlist>
+ </p>
+ </sect2>
+ <sect2 id="repackaged origtargz">
+ <heading>Repackaged upstream source</heading>
+ <p>
+You <strong>should</strong> upload packages with a pristine source
+tarball if possible, but there are various reasons why it might not be
+possible. This is the case if upstream does not distribute the source
+as gzipped tar at all, or if upstream's tarball contains non-DFSG-free
+material that you must remove before uploading.
+ </p>
+ <p>
+In these cases the developer must construct a suitable .orig.tar.gz
+file himself. 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 changes in a separate <tt>.diff.gz</tt> and still has
+a version number composed of <tt><upstream-version></tt> and
+<tt><debian-revision></tt>.
+ </p>
+ <p>
+There may be cases where it is desirable to repackage the source even
+though upstream distributes a <tt>.tar.gz</tt> that could in principle
+be used in its pristine form. The most obvious is if
+<em>significant</em> space savings can be achieved by recompressing
+the tar archive or by removing genuinely useless cruft from the
+upstream archive. Use your own discretion here, but be prepared to
+defend your decision if you repackage source that could have been
+pristine.
+ </p>
+ <p>
+A repackaged .orig.tar.gz
+ </p>
+ <p>
+ <enumlist>
+ <item>
+<p>
+<strong>must</strong> contain detailed information how
+the repackaged source was obtained, and how this can be reproduced, in
+<file>README.Debian-source</file> or a similar file. This file should
+be in the <file>diff.gz</file> part of the Debian source package,
+usually in the <file>debian</file> directory, <em>not</em> in the
+repackaged <file>orig.tar.gz</file>. It is also a good idea to provide a
+<tt>get-orig-source</tt> target in your <file>debian/rules</file> file
+that repeats the process, as described in the Policy Manual, <url
+id="&url-debian-policy;ch-source.html#s-debianrules" name="Main
+building script: debian/rules">.
+</p>
+ </item>
+ <item>
+<strong>should not</strong> contain any file that does not come from the
+upstream author(s), or whose contents has been changed by you.
+<footnote>
+As a special exception, if the omission of non-free files would lead
+to the source failing to build without assistance from the Debian
+diff, it might be appropriate to instead edit the files, omitting only
+the non-free parts of them, and/or explain the situation in a
+README.Debian-source <!-- or similarly named --> file in the root of the source
+tree. But in that case please also urge the upstream author to make
+the non-free components easier seperable from the rest of the source.
+</footnote>
+ </item>
+ <item>
+<p>
+<strong>should</strong>, except where impossible for legal reasons,
+preserve the entire building and portablility infrastructure provided
+by the upstream author. For example, it is not a sufficient reason for
+omitting a file that it is used only when building on
+MS-DOS. Similarly, a Makefile provided by upstream should not be
+omitted even if the first thing your <file>debian/rules</file> does is
+to overwrite it by running a configure script.
+</p>
+<p>
+(<em>Rationale:</em> It is common for Debian users who need to build
+software for non-Debian platforms to fetch the source from a Debian
+mirror rather than trying to locate a canonical upstream distribution
+point).
+</p> </item>
+ <item>
+<strong>should</strong> use
+<tt><packagename>-<upstream-version>.orig</tt> as the name
+of the top-level directory in its tarball. This makes it possible to
+distinguish pristine tarballs from repackaged ones. + </item>
+ <item>
+<strong>should</strong> be gzipped with maximal compression.
+ </item>
+ </enumlist>
+ </p>
+ <p>
+The canonical way to meet the latter two points is to let
+<tt>dpkg-source -b</tt> construct the repackaged tarball from an
+unpacked directory.
+ </p>
+ </sect2>
+ <sect2 id="changed-binfiles">
+ <heading>Changing binary files in <tt>diff.gz</tt></heading>
+ <p>
+Sometimes it is necessary to change binary files contained in the
+original tarball, or to add binary files that are not in it.
+If this is done by simply copying the files into the debianized source
+tree, <prgn>dpkg-source</prgn> will not be able to handle this. On the
+other hand, according to the guidelines given above, you cannot
+include such a changed binary file in a repackaged
+<file>orig.tar.gz</file>. Instead, include the file in the
+<file>debian</file> directory in <prgn>uuencode</prgn>d (or similar)
+form
+<footnote>
+The file should have a name that makes it clear which binary file it
+encodes. Usually, some postfix indicating the encoding should be
+appended to the original filename.
+</footnote>.
+The file would then be decoded and copied to its place during the
+build process. Thus the change will be visible quite easy.
+</p>
+<p>
+Some packages use <prgn>dbs</prgn> to manage patches to their upstream
+source, and always create a new <tt>orig.tar.gz</tt> file that
+contains the real <tt>orig.tar.gz</tt> in its toplevel directory. This
+is questionable with respect to the preference for pristine source. On
+the other hand, it is easy to modify or add binary files in this case:
+Just put them into the newly created <tt>orig.tar.gz</tt> file,
+besides the real one, and copy them to the right place during the
+build process.
+ </p>
+ </sect2>
+ </sect1>
+
+
</sect>
</chapt>
out all the bugs you submitted, you just have to visit
<tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>.
- <sect1 id="submit-many-bugs">Reporting lots of bugs at once
+ <sect1 id="submit-many-bugs">Reporting lots of bugs at once (mass bug filing)
<p>
Reporting a great number of bugs for the same problem on a great
number of different packages — i.e., more than 10 — is a deprecated
<p>
If you report more than 10 bugs on the same topic at once, it is
recommended that you send a message to &email-debian-devel; describing
-your intention before submitting the report. This will allow other
+your intention before submitting the report, and mentioning the
+fact in the subject of your mail. This will allow other
developers to verify that the bug is a real problem. In addition, it
will help prevent a situation in which several maintainers start
filing the same bug report simultaneously.
~ianmdlvl / developers-reference.git / blobdiff