chiark / gitweb /
Re-applied comments from SGML source to the DocBook files.
authordebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Wed, 27 Jun 2007 12:57:32 +0000 (12:57 +0000)
committerdebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Wed, 27 Jun 2007 12:57:32 +0000 (12:57 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/developers-reference/trunk@4906 313b444b-1b9f-4f58-a734-7bb04f332e8d

best-pkging-practices.dbk
beyond-pkging.dbk
l10n.dbk
new-maintainer.dbk
pkgs.dbk
resources.dbk
scope.dbk
tools.dbk

index f1130c2..63b7f87 100644 (file)
@@ -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>
+<!-- FIXME: Find a good debhelper example with multiple configure/make
+     cycles -->
 </section>
 
 </section>
@@ -318,6 +320,10 @@ implementation?  more features?  different features?  Why should I choose this
 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>
 
@@ -601,6 +607,17 @@ NEWS.Debian file in your package.  No news is good news!
 
 </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>
@@ -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-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>
@@ -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>
+<!-- TODO: mozilla extension policy, once that becomes available -->
 </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>
@@ -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
+<!-- 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>
index ffbfd3a..f5c7be8 100644 (file)
@@ -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>
+<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
 </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>
+<!-- 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
index 76203f3..dec77c4 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).
+<!-- TODO: add the i18n tag to the bug? -->
 </para>
 </section>
 
index e277466..c52583a 100644 (file)
@@ -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
-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>
index 68e24f1..5004933 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>
+<!-- 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,
@@ -2262,6 +2264,7 @@ shows build dependencies which are not considered by britney.
 <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
index a167915..cc04f3d 100644 (file)
@@ -337,6 +337,7 @@ questions.
 
 <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>
@@ -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>
+<!-- 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">
index 5e706c2..d4788a6 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>
+<!-- FIXME: rewrites -->
 <para>
 The procedures discussed within include how to become a maintainer (<xref
 linkend="new-maintainer"/> ); how to create new packages (<xref
index 7f18532..de5cfd4 100644 (file)
--- a/tools.dbk
+++ b/tools.dbk
@@ -538,6 +538,28 @@ unpacking it.
 </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>
-