Re-applied comments from SGML source to the DocBook files.

git-svn-id: svn://anonscm.debian.org/ddp/developers-reference/trunk@4906 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index f1130c201501d35ba885d879ae58665001d8cb50..63b7f87c44284a764154b18c8d440ce5e4c2e8f6 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -142,6 +142,8 @@ the same software but with different configuration options.  The <systemitem
 role="package">vim</systemitem> source package is an example of how to manage
 this using an hand-crafted <filename>debian/rules</filename> file.
 </para>
 role="package">vim</systemitem> source package is an example of how to manage
 this using an hand-crafted <filename>debian/rules</filename> file.
 </para>

+<!-- FIXME: Find a good debhelper example with multiple configure/make
+     cycles -->

 </section>
 
 </section>
 </section>
 
 </section>


@@ -318,6 +320,10 @@ implementation?  more features?  different features?  Why should I choose this
 package.
 </para>
 </listitem>
 package.
 </para>
 </listitem>

+<!-- FIXME: what's this?
+(the second questions is about the class of packages, and
+this about this particular package, if you have information related to both).
+-->

 </itemizedlist>
 </section>
 
 </itemizedlist>
 </section>
 


@@ -601,6 +607,17 @@ NEWS.Debian file in your package.  No news is good news!
 
 </section>
 
 
 </section>
 

+<!--
+<section id="pkg-mgmt-cvs">
+<title>Managing a package with CVS</title>
+<para>
+FIXME: presentation of cvs-buildpackage, updating sources
+via CVS (debian/rules refresh).
+<ulink url="http://www.debian.org/devel/cvs_packages">"http://www.debian.org/devel/cvs_packages"</ulink>
+</para>
+</section>
+-->
+

 <section id="bpp-debian-maint-scripts">
 <title>Best practices for maintainer scripts</title>
 <para>
 <section id="bpp-debian-maint-scripts">
 <title>Best practices for maintainer scripts</title>
 <para>


@@ -1303,6 +1320,15 @@ easier, for instance, to keep URLs up to date across multiple files.
 
 <section id="bpp-common-situations">
 <title>Common packaging situations</title>
 
 <section id="bpp-common-situations">
 <title>Common packaging situations</title>

+<!--
+<section id="bpp-kernel">
+<title>Kernel modules/patches</title>
+<para>
+FIXME: Heavy use of kernel-package. provide files in
+/etc/modutils/ for module configuration.
+</para>
+</section>
+-->

 <section id="bpp-autotools">
 <title>Packages using <command>autoconf</command>/<command>automake</command></title>
 <para>
 <section id="bpp-autotools">
 <title>Packages using <command>autoconf</command>/<command>automake</command></title>
 <para>


@@ -1417,9 +1443,30 @@ role="package">common-lisp-controller</systemitem>, about which see
 <filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>.
 </para>
 </listitem>
 <filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>.
 </para>
 </listitem>

+<!-- TODO: mozilla extension policy, once that becomes available -->

 </itemizedlist>
 </section>
 
 </itemizedlist>
 </section>
 

+<!--
+<section id="custom-config-files">
+<title>Custom configuration files</title>
+<para>
+FIXME: speak of "ucf", explain solution with a template,
+explain conf.d directories
+</para>
+</section>
+<section id="config-with-db">
+<title>Use of an external database</title>
+<para>
+FIXME: The software may require a database that you need to setup.
+But the database may be local or distant. Thus you can't depend
+on a database server but just on the corresponding library.
+
+sympa may be an example package
+</para>
+</section>
+-->
+

 <section id="bpp-archindepdata">
 <title>Architecture-independent data</title>
 <para>
 <section id="bpp-archindepdata">
 <title>Architecture-independent data</title>
 <para>


@@ -1613,6 +1660,7 @@ come from the upstream author(s), or whose contents has been changed by you.
 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
 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.  </para> </footnote>
 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.  </para> </footnote>

diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk
index ffbfd3ad16cedfe432fea6c8389802d195c91b99..f5c7be842f3b14f8f1d84fcc54579dfec6f6fda6 100644 (file)
--- a/beyond-pkging.dbk
+++ b/beyond-pkging.dbk
@@ -171,6 +171,7 @@ given source package via <xref linkend="pkg-tracking-system"/> .  You can do so
 by using the <literal>&lt;package&gt;@packages.qa.debian.org</literal> email
 address.
 </para>
 by using the <literal>&lt;package&gt;@packages.qa.debian.org</literal> email
 address.
 </para>

+<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->

 </section>
 
 <section id="mia-qa">
 </section>
 
 <section id="mia-qa">


@@ -295,6 +296,12 @@ Sponsoring a package means uploading a package for a maintainer who is not able
 to do it on their own, a new maintainer applicant.  Sponsoring a package also
 means accepting responsibility for it.
 </para>
 to do it on their own, a new maintainer applicant.  Sponsoring a package also
 means accepting responsibility for it.
 </para>

+<!-- FIXME: service down
+<para>
+If you wish to volunteer as a sponsor, you can sign up at <ulink
+url="http://www.internatif.org/bortzmeyer/debian/sponsor/">http://www.internatif.org/bortzmeyer/debian/sponsor/</ulink>.
+</para>
+-->

 <para>
 New maintainers usually have certain difficulties creating Debian packages —
 this is quite understandable.  That is why the sponsor is there, to check the
 <para>
 New maintainers usually have certain difficulties creating Debian packages —
 this is quite understandable.  That is why the sponsor is there, to check the

diff --git a/l10n.dbk b/l10n.dbk
index 76203f390797b9b817e873cdcfadf3868851fa52..dec77c462750511fb1bd6c1c400f52b34938ab49 100644 (file)
--- a/l10n.dbk
+++ b/l10n.dbk
@@ -157,6 +157,7 @@ speakers.
 The best solution may be to mark the bug as forwarded to upstream, and forward
 it to both the previous translator and his/her team (using the corresponding
 debian-l10n-XXX mailing list).
 The best solution may be to mark the bug as forwarded to upstream, and forward
 it to both the previous translator and his/her team (using the corresponding
 debian-l10n-XXX mailing list).

+<!-- TODO: add the i18n tag to the bug? -->

 </para>
 </section>
 
 </para>
 </section>
 

diff --git a/new-maintainer.dbk b/new-maintainer.dbk
index e277466cade7413795949a7c2a63db3d46171957..c52583aa70748eaa0041ac1751d3ffbac8122169 100644 (file)
--- a/new-maintainer.dbk
+++ b/new-maintainer.dbk
@@ -77,7 +77,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 Developers, and who are willing to criticize and upload your
 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 Developers, and who are willing to criticize and upload your

-packages for you.  Please read the unofficial debian-mentors FAQ at <ulink
+packages for you.
+<!-- FIXME - out of order
+Those who are seeking a
+sponsor can request one at <ulink url="http://www.internatif.org/bortzmeyer/debian/sponsor/"></ulink>.
+-->
+Please read the unofficial debian-mentors FAQ at <ulink

 url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html"></ulink> first.
 </para>
 <para>
 url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html"></ulink> first.
 </para>
 <para>

diff --git a/pkgs.dbk b/pkgs.dbk
index 68e24f1f96ca6d41ebfecf30d7915214faac8ae9..5004933cb3ef7cb3ac35836c82875b4dc310450e 100644 (file)
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -812,6 +812,8 @@ outstanding security problems, helping maintainers with security problems or
 fixing them themselves, sending security advisories, and maintaining
 security.debian.org.
 </para>
 fixing them themselves, sending security advisories, and maintaining
 security.debian.org.
 </para>

+<!-- information about the security database goes here once it's ready -->
+<!-- (mdz) -->

 <para>
 When you become aware of a security-related bug in a Debian package, whether or
 not you are the maintainer, collect pertinent information about the problem,
 <para>
 When you become aware of a security-related bug in a Debian package, whether or
 not you are the maintainer, collect pertinent information about the problem,


@@ -2262,6 +2264,7 @@ shows build dependencies which are not considered by britney.
 <section id="outdated">
 <title>out-of-date</title>
 <para>
 <section id="outdated">
 <title>out-of-date</title>
 <para>

+<!-- FIXME: better rename this file than document rampant professionalism? -->

 For the testing migration script, outdated means: There are different versions
 in unstable for the release architectures (except for the architectures in
 fuckedarches; fuckedarches is a list of architectures that don't keep up (in
 For the testing migration script, outdated means: There are different versions
 in unstable for the release architectures (except for the architectures in
 fuckedarches; fuckedarches is a list of architectures that don't keep up (in

diff --git a/resources.dbk b/resources.dbk
index a1679154178c1919efa0328c09673b21dacaa3e3..cc04f3d268b8e8b116e10ec10f58351134f3f70d 100644 (file)
--- a/resources.dbk
+++ b/resources.dbk
@@ -337,6 +337,7 @@ questions.
 
 <section id="servers-cvs">
 <title>The CVS server</title>
 
 <section id="servers-cvs">
 <title>The CVS server</title>

+<!-- TODO: document svn.debian.org, arch.debian.org also -->

 <para>
 Our CVS server is located on <literal>cvs.debian.org</literal>.
 </para>
 <para>
 Our CVS server is located on <literal>cvs.debian.org</literal>.
 </para>


@@ -950,6 +951,63 @@ announcement will be posted to
 Though ftp-master is restricted, a copy of the installation is available to all
 developers on <literal>merkel.debian.org</literal>.
 </para>
 Though ftp-master is restricted, a copy of the installation is available to all
 developers on <literal>merkel.debian.org</literal>.
 </para>

+<!-- FIXME: delete it or keep it for historical purposes?
+<para>
+All Debian developers have write access to the <filename>unchecked</filename>
+directory in order to upload their packages; they also have that access
+to the <filename>reject</filename> directory in order to remove their bad uploads
+or to move some files back to the <filename>unchecked</filename> directory. But
+all the other directories are only writable by the ftpmasters, which is
+why you cannot remove an upload once it has been accepted.
+</para>
+
+<section id="delayed-incoming-broken">
+<title>Delayed incoming</title>
+<para>
+<emphasis>Note:</emphasis> This description here is currently not working, because
+ftp-master is restricted. Please see <xref linkend="delayed-incoming"/> for
+the currently working way.
+</para>
+<para>
+The <filename>unchecked</filename> directory has a special <filename>DELAYED</filename>
+subdirectory. It is itself subdivided in nine directories
+called <filename>1-day</filename> to <filename>9-day</filename>. Packages which are uploaded to
+one of those directories will be moved to the real unchecked
+directory after the corresponding number of days.
+This is done by a script which is run each day and which moves the
+packages between the directories. Those which are in "1-day" are
+installed in <filename>unchecked</filename> while the others are moved to the 
+adjacent directory (for example, a package in <filename>5-day</filename> will
+be moved to <filename>4-day</filename>). This feature is particularly useful
+for people who are doing non-maintainer uploads. Instead of
+waiting before uploading a NMU, it is uploaded as soon as it is
+ready, but to one of those <filename>DELAYED/<varname>x</varname>-day</filename> directories.
+That leaves the corresponding number of days for the maintainer
+to react and upload another fix themselves if they are not
+completely satisfied with the NMU. Alternatively they can remove
+the NMU.
+</para>
+<para>
+The use of that delayed feature can be simplified with a bit
+of integration with your upload tool.  For instance, if you use 
+<command>dupload</command> (see <xref linkend="dupload"/>), you can add this
+snippet to your configuration file:
+<screen>
+$delay = ($ENV{DELAY} || 7);
+$cfg{'delayed'} = {
+         fqdn => "&ftp-master-host;",
+         login => "yourdebianlogin",
+         incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
+         dinstall_runs => 1,
+         method => "scpb"
+};
+</screen>
+Once you've made that change, <command>dupload</command> can be used to
+easily upload a package in one of the delayed directories:
+<literal>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</literal>
+</para>
+</section>
+-->

 </section>
 
 <section id="pkg-info">
 </section>
 
 <section id="pkg-info">

diff --git a/scope.dbk b/scope.dbk
index 5e706c20539b946fceff45168e6715a0f22163b6..d4788a6ea0eefe9d26c9ccaff1142e40ce0133e5 100644 (file)
--- a/scope.dbk
+++ b/scope.dbk
@@ -7,6 +7,7 @@
 The purpose of this document is to provide an overview of the recommended
 procedures and the available resources for Debian developers.
 </para>
 The purpose of this document is to provide an overview of the recommended
 procedures and the available resources for Debian developers.
 </para>

+<!-- FIXME: rewrites -->

 <para>
 The procedures discussed within include how to become a maintainer (<xref
 linkend="new-maintainer"/> ); how to create new packages (<xref
 <para>
 The procedures discussed within include how to become a maintainer (<xref
 linkend="new-maintainer"/> ); how to create new packages (<xref

diff --git a/tools.dbk b/tools.dbk
index 7f18532b7a5732b7fbeac4265c9fca3ee915d719..de5cfd4b13f639da4e42fd3772aa6ed29a1f28b9 100644 (file)
--- a/tools.dbk
+++ b/tools.dbk
@@ -538,6 +538,28 @@ unpacking it.
 </section>
 
 </section>
 </section>
 
 </section>

-
+<!-- FIXME: add the following
+
+questionable:
+  dbs (referred to above)
+  dpatch (referred to above)
+  debarchiver
+  ucf
+  dpkg-awk
+  grep-dctrl
+  d-shlibs
+  wajig
+  magpie
+  apt-dpkg-ref
+  apt-show-source
+  apt-show-versions
+  pdbv
+  epm
+  apt-src
+  apt-build
+
+rejected:
+  debaux: too new, unmaintained?
+  dh-make-perl: too new, unmaintained?
+-->

 </appendix>
 </appendix>

-