<!ENTITY % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!ENTITY cvs-rev "$Revision: 1.251 $">
+ <!ENTITY cvs-rev "$Revision: 1.257 $">
<!-- if you are translating this document, please notate the CVS
revision of the original developer's reference in cvs-en-rev -->
but are waiting for your new maintainer application to go through, you
might be able find a sponsor to upload your package for you. Sponsors
are people who are official Debian maintainers, and who are willing to
-criticize and upload your packages for you. Those who are seeking a
-sponsor can request one at <url id="&url-sponsors;">. Please read the
+criticize and upload your packages for you.
+<!-- FIXME - out of order
+Those who are seeking a
+sponsor can request one at <url id="&url-sponsors;">.
+-->
+Please read the
inofficial debian-mentors FAQ at <url id="&url-mentors;"> first.
<p>
If you wish to be a mentor and/or sponsor, more information is
<qref id="devel-db">Debian developers' LDAP database</qref> (this
information is only accessible to Debian developers).
Don't forget to remove the "on vacation" flag when you come back!
+ <p>
+Ideally, you should sign up at the
+<url id="http://nm.debian.org/gpg.php" name="GPG coordination site">
+when booking a holiday and check if anyone there is looking for signing.
+This is especially important when people go to exotic places
+where we don't have any developers yet but
+where there are people who are interested in applying.
<sect id="upstream-coordination">Coordination with upstream developers
<p>
There are other additional channels dedicated to specific subjects.
<em>#debian-bugs</em> is used for coordinating bug squash parties.
-<em>#debian-boot</em> is used to coordinate the work on the boot
-floppies (i.e., the installer).
-<!-- FIXME: is boot-floppies an anachronism, or still the channel name? -->
+<em>#debian-boot</em> is used to coordinate the work on the debian-installer.
<em>#debian-doc</em> is
occasionally used to talk about documentation, like the document you are
reading. Other channels are dedicated to an architecture or a set of
Channels dedicated to Debian also exist on other IRC networks, notably on
the <url name="Open and free technology community (OFTC)"
id="http://www.oftc.net/"> IRC network.
+ <p>
+To get a cloak on freenode, you send Göran Weinholt <weinholt@debian.org>
+a signed mail where you tell what your nick is.
+Put "cloak" somewhere in the Subject: header.
+The nick should be registered:
+<url id="http://freenode.net/faq.shtml#nicksetup" name="Nick Setup Page">.
+The mail needs to be signed by a key in the Debian keyring.
+Please see
+<url id="http://freenode.net/faq.shtml#projectcloak" name="Freenodes documentation">
+for more information about cloaks.
<sect id="doc-rsrcs">Documentation
<p>
On the other hand, a CD-ROM vendor could easily check the individual
package licenses of the packages in <em>non-free</em> and include as
-many on the CD-ROMs as he's allowed to. (Since this varies greatly from
+many on the CD-ROMs as it's allowed to. (Since this varies greatly from
vendor to vendor, this job can't be done by the Debian developers.)
<p>
Note that the term "section" is also used to refer to categories
and <tt>&non-us-host;</tt>.
<p>
Packages are uploaded by all the maintainers into a directory called
-<file>unchecked</file>. This directory is scanned every 15 minutes by
+<file>UploadQueue</file>.
+This directory is scanned every few minutes by a daemon called
+<prgn>queued</prgn>, <file>*.command</file>-files are executed, and
+remaining and correctly signed <file>*.changes</file>-files are moved
+together with their corresponding files to the <file>unchecked</file>
+directory.
+This directory is not visible for most Developers, as ftp-master is restricted;
+it is scanned every 15 minutes by
the <prgn>katie</prgn> script, which verifies the integrity of the uploaded
packages and their cryptographic signatures.
If the package is considered ready to be installed, it
is moved into the <file>accepted</file> directory. If this is the first upload of
-the package, it is moved to the <file>new</file> directory, where it waits
+the package (or it has new binary packages),
+it is moved to the <file>new</file> directory, where it waits
for approval by the ftpmasters. If the package contains files to be installed
"by hand" it is moved to the <file>byhand</file> directory, where it waits
for manual installation by the ftpmasters. Otherwise, if any error has been detected,
Once the package is accepted, the system sends a confirmation
mail to the maintainer and closes all the bugs marked as fixed by the upload,
and the auto-builders may start recompiling it. The package is now publicly
-accessible at <url id="&url-incoming;"> (there is no
-such URL for packages in the non-US archive) until it is really installed
-in the Debian archive. This happens only once a day, the package
+accessible at <url id="&url-incoming;">
+until it is really installed
+in the Debian archive.
+This happens only once a day
+(and is also called `dinstall run' for historical reasons);
+the package
is then removed from incoming and installed in the pool along with all
the other packages. Once all the other updates (generating new
<file>Packages</file> and <file>Sources</file> index files for example) have been
or `experimental', the announcement will be posted to
&email-debian-devel-changes; instead.
<p>
+Though ftp-master is restricted, a copy of the installation is available
+to all developers on <tt>&ftp-master-mirror;</tt>.
+<!-- FIXME: delete it or keep it for historical purposes?
+ <p>
All Debian developers have write access to the <file>unchecked</file>
directory in order to upload their packages; they also have that access
to the <file>reject</file> directory in order to remove their bad uploads
</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>
+-->
<sect id="pkg-info">Package information
<sect1 id="madison">The <prgn>madison</prgn> utility
<p>
<prgn>madison</prgn> is a command-line utility that is available
-on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
+on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>, and on
+the mirror on <tt>&ftp-master-mirror;</tt>. It
uses a single argument corresponding to a package name. In result
it displays which version of the package is available for each
architecture and distribution combination. An example will explain
Some bugs may even be dropped to wishlist severity when the requested
change is just cosmetic.
<item>
+If the bug is real but the same problem has already been reported by
+someone else, then the two relevant bug reports should be merged
+into one using the merge command of the BTS.
+In this way, when the
+bug is fixed, all of the submitters will be informed of this.
+(Note, however, that emails sent to one bug report's submitter won't
+automatically be sent to the other report's submitter.)
+For more
+details on the technicalities of the merge command and its relative,
+the unmerge command, see the BTS control server documentation.
+ <item>
The bug submitter may have forgotten to provide some information, in which
case you have to ask them the required information. You may use the
<tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't
most concise entry and the easiest to integrate with the text of the
<file>changelog</file>.
<p>
-If an upload is identified as <ref id="nmu" name="Non-maintainer upload (NMU)">
+If an upload is identified as <qref id="nmu">Non-maintainer upload (NMU)</qref>
(and that is the case if the name of the person who commits this change
is not exactly the same as any one of Maintainer or Uploader,
except if the maintainer is the qa group),
whether it is already a matter of public knowledge.
<p>
-There are a few ways a developer can learn of a security problem:
+There are a few ways developers can learn of a security problem:
<list compact>
- <item>he notices it on a public forum (mailing list, web site, etc.)
+ <item>they notice it on a public forum (mailing list, web site, etc.)
<item>someone files a bug report
<item>someone informs them via private email
</list>
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>
<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.
able to do it on their own, a new maintainer applicant. Sponsoring a package
also means accepting responsibility for it.
<p>
+ <!-- FIXME: service down
If you wish to volunteer as a sponsor, you can sign up at <url
id="&url-sponsors;">.
<p>
+ -->
New maintainers usually have certain difficulties creating Debian packages
— this is quite understandable. That is why the sponsor is there, to check
the package and verify that it is good enough for inclusion in Debian.
~ianmdlvl / developers-reference.git / blobdiff