chiark / gitweb /
gender neutral, current incoming, orig.tar.gz handling, merging bugs, vacation and...
authoraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 23 Jan 2005 23:17:56 +0000 (23:17 +0000)
committeraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 23 Jan 2005 23:17:56 +0000 (23:17 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2836 313b444b-1b9f-4f58-a734-7bb04f332e8d

debian/changelog
developers-reference.sgml

index f4660b2..1c7fe07 100644 (file)
@@ -1,17 +1,20 @@
-developers-reference (3.3.7) unstable; urgency=low
-
-  * Frédéric Bothamy
-    - French translation updated to version 3.3.6
-  
- --
-
 developers-reference (3.3.6) unstable; urgency=low
 
   * Andreas Barth
     - closes: and NMUs/experimental uploads. Closes: #284714
     - madison is on merkel.
+    - more gender-neutral. Closes: #290583, #290584
+    - explain current incoming. Closes: #290019
+    - remove broken sponsoring URL. Closes: #291698
+    - add handling hints about orig.tar.gz. Thanks, Frank. Closes: #278524
+    - duplicate bug reports should be merged. Closes: #285381
+    - if you're on vacation, please check whether someone needs keysigning.
+      Closes: #285458
+    - freenode has developer cloacks. Closes: #285687
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.6
 
- -- Andreas Barth <aba@not.so.argh.org>  Wed,  8 Dec 2004 03:03:01 -0700
+ -- Andreas Barth <aba@not.so.argh.org>  Sun, 23 Jan 2005 16:08:49 -0700
 
 developers-reference (3.3.5) unstable; urgency=low
 
index 80bd2ae..e5cec45 100644 (file)
@@ -6,7 +6,7 @@
   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.254 $">
+  <!ENTITY cvs-rev "$Revision: 1.255 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -259,8 +259,12 @@ In addition, if you have some packages ready for inclusion in Debian,
 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
@@ -364,6 +368,13 @@ The other thing to do is to mark yourself as "on vacation" in the
 <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
@@ -546,9 +557,7 @@ all the files.
        <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
@@ -564,6 +573,16 @@ French speaking people interested in Debian's development.
 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&ouml;ran Weinholt &lt;weinholt@debian.org&gt;
+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
@@ -830,7 +849,7 @@ commercial distribution, for example.
        <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
@@ -1105,12 +1124,20 @@ directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
 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,
@@ -1119,9 +1146,12 @@ the package is refused and is moved to the <file>reject</file> directory.
 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
@@ -1136,6 +1166,10 @@ If a package is released with <tt>Distribution:</tt> set to `unstable'
 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
@@ -1184,7 +1218,7 @@ $cfg{'delayed'} = {
 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 &lt;changes-file&gt;</example>
-
+-->
 
 
     <sect id="pkg-info">Package information
@@ -2037,6 +2071,17 @@ inflate the severity of bugs to make sure their bugs are fixed quickly.
 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
@@ -2182,10 +2227,10 @@ case depends on the nature of the problem and corresponding fix, and
 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>
@@ -3449,6 +3494,195 @@ These are just some subjective hints, advice and pointers collected
 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/&lt;packagename&gt;_&lt;upstream-version&gt;.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.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>&lt;packagename&gt;-&lt;upstream-version&gt;(.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>&lt;upstream-version&gt;</tt> and
+<tt>&lt;debian-revision&gt;</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>&lt;packagename&gt;-&lt;upstream-version&gt;.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>