mention how the vacation notices should include [VAC] in the subject; change the...

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index f64955c1f615143efec57b1d292507eec09b0037..db32815a0984605c6b9071818ba4c399ff82349a 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -5,7 +5,7 @@
   <!-- common, language independant entities -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
   <!-- CVS revision of this document -->
   <!-- common, language independant entities -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
   <!-- CVS revision of this document -->

-  <!entity cvs-rev "$Revision: 1.68 $">
+  <!entity cvs-rev "$Revision: 1.71 $">

 
   <!-- if you are translating this document, please notate the RCS
        revision of the developers reference here -->
 
   <!-- if you are translating this document, please notate the RCS
        revision of the developers reference here -->


@@ -309,10 +309,14 @@ you're on vacation.
 In order to inform the other developers, there's two things that you should do.
 First send a mail to &email-debian-private; giving the period of time when
 you will be on vacation.  You can also give some special instructions on what to
 In order to inform the other developers, there's two things that you should do.
 First send a mail to &email-debian-private; giving the period of time when
 you will be on vacation.  You can also give some special instructions on what to

-do if any problem occurs. Next you should update your information
+do if any problem occurs. Be aware that some people don't care for vacation
+notices and don't want to read them; you should prepend "[VAC] " to the
+subject of your message so that it can be easily filtered.
+       <p>
+Next you should update your information

 available in the Debian LDAP database and mark yourself as ``on vacation''
 (this information is only accessible to debian developers). Don't forget
 available in the Debian LDAP database and mark yourself as ``on vacation''
 (this information is only accessible to debian developers). Don't forget

-to remove the ``on vacation'' flag when you come back.
+to remove the ``on vacation'' flag when you come back!

 
       <sect id="upstream-coordination">Coordination With Upstream Developers
        <p>
 
       <sect id="upstream-coordination">Coordination With Upstream Developers
        <p>


@@ -915,11 +919,38 @@ better feel of what is going on, and what is new, in the project.
          </list>
 
 
          </list>
 
 

+      <sect id="upload-checking">Checking the package prior to upload
+         <p>
+Before you upload your package, you should do basic testing on it.  At
+a minimum, you should try the following activities (you'll need to
+have an older version of the same Debian package around):
+<list>
+              <item>
+Install the package and make sure the software works, or upgrade the
+package from an older version to your new version if a Debian package
+for it already exists.
+             <item>
+Run <prgn>lintian</prgn> over the package.  You can run
+<prgn>lintian</prgn> as follows: <tt>lintian -v
+<var>package-version</var>.changes</tt>. This will check the source
+package as well as the binary package.  If you don't understand the
+output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
+switch, which will cause <prgn>lintian</prgn> to output a very verbose
+description of the problem.
+               <p>
+Normally, a package should <em>not</em> be uploaded if it causes lintian
+to emit errors (they will start with <tt>E</tt>).
+               <p>
+For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
+             <item>
+Downgrade the package to the previous version (if one exists) &mdash; this
+tests the <tt>postrm</tt> and <tt>prerm</tt> scripts.
+             <item>
+Remove the package, then reinstall it.
+           </list>

 
 
 
 

-      <sect id="uploading">Uploading a package
-
-       <sect1>Generating the changes file
+      <sect>Generating the changes file

          <p>
 When a package is uploaded to the Debian FTP archive, it must be
 accompanied by a <tt>.changes</tt> file, which gives directions to the
          <p>
 When a package is uploaded to the Debian FTP archive, it must be
 accompanied by a <tt>.changes</tt> file, which gives directions to the


@@ -934,29 +965,10 @@ All of these fields are mandatory for a Debian upload.  See the list
 of control fields in the <url id="&url-debian-policy;" name="Debian
 Policy Manual"> for the contents of these fields.  You can close bugs
 automatically using the <tt>Description</tt> field, see <ref
 of control fields in the <url id="&url-debian-policy;" name="Debian
 Policy Manual"> for the contents of these fields.  You can close bugs
 automatically using the <tt>Description</tt> field, see <ref

-id="upload-bugfix">.  Only the <tt>Distribution</tt> field is
-discussed in this section, since it relates to the archive maintenance
-policies.
+id="upload-bugfix">.

 
 
 
 

-       <sect1 id="upload-dist">Picking a distribution
-         <p>
-Notably, the <tt>Distribution</tt> field, which originates from the
-<file>debian/changelog</file> file, indicates which distribution the
-package is intended for.  There are four possible values for this
-field: `stable', `unstable', `frozen', or `experimental'; these values
-can also be combined. Or, if Debian has been frozen, and you
-want to get a bug-fix release into <em>frozen</em>, you would set the
-distribution to `frozen unstable'.  (See <ref id="upload-frozen"> for
-more information on when to upload to <em>frozen</em>.)  Note that it
-never makes sense to combine the <em>experimental</em> distribution with
-anything else.
-         <p>
-You should avoid combining `stable' with others because of potential
-problems with library dependencies (for your package and for the package
-built by the build daemons for other architecture).
-See <ref id="upload-stable"> for more information on when and how to
-upload to <em>stable</em>.
+       <sect1>The original source tarball

          <p>
 The first time a version is uploaded which corresponds to a particular
 upstream version, the original source tar file should be uploaded and
          <p>
 The first time a version is uploaded which corresponds to a particular
 upstream version, the original source tar file should be uploaded and


@@ -979,6 +991,32 @@ is some reason why this is not the case, the new version of the
 original source should be uploaded, possibly by using the <tt>-sa</tt>
 flag.
 
 original source should be uploaded, possibly by using the <tt>-sa</tt>
 flag.
 

+
+       <sect1 id="upload-dist">Picking a distribution
+         <p>
+The <tt>Distribution</tt> field, which originates from the first line of
+the <file>debian/changelog</file> file, indicates which distribution the
+package is intended for.
+         <p>
+There are four possible values for this field: `stable', `unstable',
+`frozen', and `experimental'. Normally, packages are uploaded into
+<em>unstable</em>.
+         <p>
+These values can be combined, but only a few combinations make sense.
+If Debian has been frozen, and you want to get a bug-fix release into
+<em>frozen</em>, you would set the distribution to `frozen unstable'.
+See <ref id="upload-frozen"> for more information on uploading to
+<em>frozen</em>.
+         <p>
+You should avoid combining `stable' with others because of potential
+problems with library dependencies (for your package and for the package
+built by the build daemons for other architecture).
+See <ref id="upload-stable"> for more information on when and how to
+upload to <em>stable</em>.
+         <p>
+It never makes sense to combine the <em>experimental</em> distribution
+with anything else.
+

          <sect2 id="upload-frozen">Uploading to <em>frozen</em>
            <p>
 The Debian freeze is a crucial time for Debian.  It is our chance to
          <sect2 id="upload-frozen">Uploading to <em>frozen</em>
            <p>
 The Debian freeze is a crucial time for Debian.  It is our chance to


@@ -1058,36 +1096,7 @@ inclusion.
 
 
 
 
 
 

-       <sect1 id="upload-checking">Checking the package prior to upload
-         <p>
-Before you upload your package, you should do basic testing on it.  At
-a minimum, you should try the following activities (you'll need to
-have an older version of the same Debian package around):
-<list>
-              <item>
-Install the package and make sure the software works, or upgrade the
-package from an older version to your new version if a Debian package
-for it already exists.
-             <item>
-Run <prgn>lintian</prgn> over the package.  You can run
-<prgn>lintian</prgn> as follows: <tt>lintian -v
-<var>package-version</var>.changes</tt>. This will check the source
-package as well as the binary package.  If you don't understand the
-output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>
-switch, which will cause <prgn>lintian</prgn> to output a very verbose
-description of the problem.
-               <p>
-Normally, a package should <em>not</em> be uploaded if it causes lintian
-to emit errors (they will start with <tt>E</tt>).
-               <p>
-For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
-             <item>
-Downgrade the package to the previous version (if one exists) &mdash; this
-tests the <tt>postrm</tt> and <tt>prerm</tt> scripts.
-             <item>
-Remove the package, then reinstall it.
-           </list>
-
+      <sect id="uploading">Uploading a package

 
        <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
          <p>
 
        <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
          <p>