<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.170 $">
+ <!entity cvs-rev "$Revision: 1.187 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<sect id="user-maint">Maintaining your Debian information
<p>
-There's a LDAP database containing information about all
-developers, you can access it at <url id="&url-debian-db;">. You can
-update your password (this password is propagated to most of the machines
-that are accessible to you), your address, your country, the latitude and
-longitude of the point where you live, phone and fax numbers, your
-preferred shell, your IRC nickname, your web page and the email that
-you're using as alias for your debian.org email. Most of the information
-is not accessible to the public, for more details about this
-database, please read its online documentation that you can find
-at <url id="&url-debian-db-doc;">.
+There's a LDAP database containing information about Debian developers at
+<url id="&url-debian-db;">. You should enter your information there and
+update it as it changes. Most notably, make sure that the address where your
+debian.org email gets forwarded to is always up to date, as well as the
+address where you get your debian-private subscription if you choose to
+subscribe there.
<p>
-You have to keep the information available there up-to-date.
+For more information about the database, please see <ref id="devel-db">.
+
+
<sect id="key-maint">Maintaining your public key
<p>
<sect id="voting">Voting
<p>
-Even if Debian is not always a real democracy, Debian has democratic
-tools and uses a democratic process to elect its leader or
-to approve a general resolution. Those processes are described in
-the <url id="&url-constitution;" name="Debian Constitution">.
+Even though Debian isn't really a democracy, we use a democratic
+process to elect our leaders and to approve general resolutions.
+These procedures are defined by the
+<url id="&url-constitution;" name="Debian Constitution">.
<p>
-Democratic processes work well only if everybody take part in the
-vote, that's why you have to vote. To be able to vote you have to
-subscribe to &email-debian-devel-announce; since call for votes are sent
-there. If you want to follow the debate preceding a vote, you
-may want to subscribe to &email-debian-vote;.
+Other than the yearly leader election, votes are not routinely held, and
+they are not undertaken lightly. Each proposal is first discussed on
+the &email-debian-vote; mailing list and it requires several endorsements
+before the project secretary starts the voting procedure.
+ <p>
+You don't have to track the pre-vote discussions, as the secretary will
+issue several calls for votes on &email-debian-devel-announce; (and all
+developers are expected to be subscribed to that list). Democracy doesn't
+work well if people don't take part in the vote, which is why we encourage
+all developers to vote. Voting is conducted via GPG-signed/encrypted emails
+messages.
<p>
The list of all the proposals (past and current) is available on the
-<url id="&url-vote;" name="Debian Voting Information"> page. You will find
-there additional information about how to make a vote proposal.
+<url id="&url-vote;" name="Debian Voting Information"> page, along with
+information on how to make, second and vote on proposals.
<sect id="inform-vacation">Going on vacation gracefully
<p>
-Most developers take vacations, and usually this means that they can't
-work for Debian and they can't be reached by email if any problem occurs.
-The other developers need to know that you're on vacation so that they'll
-do whatever is needed when such a problem occurs. Usually this means that
-other developers are allowed to NMU (see <ref id="nmu">) your package if a
-big problem (release critical bugs, security update, etc.) occurs while
-you're on vacation.
+It is common for developers to have periods of absence, whether those are
+planned vacations or simply being buried in other work. The important thing
+to notice is that the other developers need to know that you're on vacation
+so that they can do whatever is needed if a problem occurs with your
+packages or other duties in the project.
+ <p>
+Usually this means that other developers are allowed to NMU (see
+<ref id="nmu">) your package if a big problem (release critical bugs,
+security update, etc.) occurs while you're on vacation. Sometimes it's
+nothing as critical as that, but it's still appropriate to let the others
+know that you're unavailable.
<p>
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. 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.
+First send a mail to &email-debian-private; with "[VAC] " prepended to the
+subject of your message<footnote>This is so that the message can be easily
+filtered by people who don't want to read vacation notices.</footnote>,
+giving the period of time when you will be on vacation. You can also give
+some special instructions on what to do if a problem occurs.
<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
-to remove the ``on vacation'' flag when you come back!
+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!
+
<sect id="upstream-coordination">Coordination with upstream developers
<p>
modify the sources of the next upstream version. Whatever changes you
need, always try not to fork from the upstream sources.
+
<sect id="rc-bugs">Managing release-critical bugs
<p>
Generally you should deal with bug reports on your packages as described in
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). <em>#debian-doc</em> is
+floppies (i.e., the 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
packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
<sect1 id="servers-bugs">The bugs server
<p>
-<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
+<tt>&bugs-host;</tt> is the canonical location for the Bug Tracking
System (BTS). If you plan on doing some statistical analysis or
processing of Debian bugs, this would be the place to do it. Please
describe your plans on &email-debian-devel; before implementing
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
<p>
-All Debian developers have accounts on <tt>bugs.debian.org</tt>.
+All Debian developers have accounts on <tt>&bugs-host;</tt>.
<sect1 id="servers-ftp-master">The ftp-master server
<p>
the lack of hyphen between "non" and "us" in the pseudo-package name
— that's for backwards compatibility). Remember to check whether or
not someone else has already reported the problem on the
-<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/nonus.debian.org" name="Bug Tracking System">.
<sect1 id="servers-www">The www-master server
<p>
submit a bug against the pseudo-package,
<package>www.debian.org</package>. Remember to check whether or not someone
else has already reported the problem on the
-<url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
+<url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.
<sect1 id="servers-people">The people web server
<p>
<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
<p>
Developers can <url name="log into the database" id="&url-debian-db-login;">
-to change their debian-private list subscription, their personal
-information, to mark themselves on vacation, etc.
-For more information on keeping your entry the developer database
-up-to-date, please see <ref id="user-maint">.
+to change various information about themselves, such as:
+<list>
+ <item>forwarding address for your debian.org email
+ <item>subscription to debian-private
+ <item>whether you are on vacation
+ <item>personal information such as your address, country,
+ the latitude and longitude of the place where you live
+ for use in <url name="the world map of Debian developers"
+ id="&url-worldmap;">, phone and fax numbers, IRC nickname
+ and web page
+ <item>password and preferred shell on Debian Project machines
+</list>
+ <p>
+Most of the information is not accessible to the public, naturally.
+For more information please read the online documentation that you can find
+at <url id="&url-debian-db-doc;">.
<p>
One can also submit their SSH keys to be used for authorization on the
official Debian machines, and even add new *.debian.net DNS entries.
the list of available keywords:
<list>
<item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
- <item><tt>bts-control</tt>: reply to mails sent to
- <email>control@bugs.debian.org</email>
+ <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
<item><tt>summary</tt>: automatic summary mails about the state of a package
<item><tt>cvs</tt>: notification of CVS commits
<item><tt>ddtp</tt>: translations of descriptions and debconf templates
<p>
The <file>debian/changelog</file> file conforms to a certain structure,
with a number of different fields. One field of note, the
-<em>distribution</em>, is described in <ref id="upload-dist">. More
+<em>distribution</em>, is described in <ref id="distribution">. More
information about the structure of this file can be found in
the Debian Policy section titled "<file>debian/changelog</file>".
<p>
There are tools to help you create entries and finalize the
<file>changelog</file> for release — see <ref id="devscripts">
and <ref id="dpkg-dev-el">.
-
-
- <sect id="upload">Package uploads
-
<p>
-When a package is uploaded to the Debian archive, it must be accompanied by
-a <tt>.changes</tt> control file, which gives directions to the archive
-maintenance software for its handling. This is generated by
-<prgn>dpkg-genchanges</prgn> during the normal package build process.
+See also <ref id="bpp-debian-changelog">.
- <sect1 id="upload-checking">Checking the package prior to upload
- <p>
+
+ <sect id="sanitycheck">Testing the package
+ <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):
<p>
For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
<item>
+Optionally run <ref id="debdiff"> to analyze changes from an older version,
+if one exists.
+ <item>
Downgrade the package to the previous version (if one exists) — this
tests the <file>postrm</file> and <file>prerm</file> scripts.
<item>
</list>
- <sect1>Layout of the source files
+ <sect id="sourcelayout">Layout of the source package
+ <p>
There are two types of Debian source packages:
- <list>
+ <list>
<item>the so-called <em>native</em> packages, where there is no
distinction between the original sources and the patches
applied for Debian
<item>the (more common) packages where there's an original source
tarball file accompanied by another file that contains the
patches applied for Debian
- </list>
+ </list>
+ <p>
For the native packages, the source package includes a Debian source control
file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
package of a non-native package includes a Debian source control file, the
original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
(<tt>.diff.gz</tt>).
+ <p>
Whether a package is native or not is determined when it is built by
<manref name="dpkg-buildpackage" section="1">. The rest of this section
relates only to non-native packages.
+ <p>
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
included in the <file>.changes</file> file. Subsequently, this very same
tar file should be used to build the new diffs and <file>.dsc</file>
files, and will not need to be re-uploaded.
+ <p>
By default, <prgn>dpkg-genchanges</prgn> and
<prgn>dpkg-buildpackage</prgn> will include the original source tar
file if and only if the Debian revision part of the source version
number is 0 or 1, indicating a new upstream version. This behavior
may be modified by using <tt>-sa</tt> to always include it or
<tt>-sd</tt> to always leave it out.
+ <p>
If no original source is included in the upload, the original
source tar-file used by <prgn>dpkg-source</prgn> when constructing the
<file>.dsc</file> file and diff to be uploaded <em>must</em> be
byte-for-byte identical with the one already in the archive.
- <sect1 id="upload-dist">Picking a distribution
+ <sect id="distribution">Picking a distribution
+ <p>
Each upload needs to specify which distribution the package is intended
for. The package build process extracts this information from the first
line of the <file>debian/changelog</file> file and places it in the
<tt>Distribution</tt> field of the <tt>.changes</tt> file.
+ <p>
There are several possible values for this field: `stable', `unstable',
`testing-proposed-updates' and `experimental'. Normally, packages are
uploaded into <em>unstable</em>.
+ <p>
Actually, there are two other possible distributions: `stable-security' and
`testing-security', but read <ref id="bug-security"> for more information on
those.
+ <p>
It is technically possible to upload a package into several distributions
at the same time but it usually doesn't make sense to use that feature
because the dependencies of the package may vary with the distribution.
In particular, it never makes sense to combine the <em>experimental</em>
distribution with anything else.
- <sect2 id="upload-stable">Uploading to <em>stable</em>
+ <sect1 id="upload-stable">Uploads to <em>stable</em>
+ <p>
Uploading to <em>stable</em> means that the package will be placed into the
<file>stable-proposed-updates</file> directory of the Debian archive for further
testing before it is actually included in <em>stable</em>.
+ <p>
Extra care should be taken when uploading to <em>stable</em>. Basically, a
package should only be uploaded to stable if one of the following happens:
<list>
<item>the package becomes uninstallable
<item>a released architecture lacks the package
</list>
+ <p>
It is discouraged to change anything else in the package that isn't
important, because even trivial fixes can cause bugs later on. Uploading
new upstream versions to fix security problems is deprecated; applying the
specific patch from the new upstream version to the old one ("back-porting"
the patch) is the right thing to do in most cases.
+ <p>
Packages uploaded to <em>stable</em> need to be compiled on systems running
<em>stable</em>, so that their dependencies are limited to the libraries
(and other packages) available in <em>stable</em>; for example, a package
exists in unstable will be rejected. Making changes to dependencies of other
packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
those other packages uninstallable, is strongly discouraged.
+ <p>
The Release Team (which can be reached at &email-debian-release;) will
regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
your package can be included in <em>stable</em>. Please be clear (and
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
- <sect2 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
+ <sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em>
+ <p>
The testing distribution is fed with packages from unstable according to the rules
explained in <ref id="testing">. However, the release manager may stop the testing
scripts when he wants to freeze the distribution. In that case, you may want to
upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
+ <p>
Keep in mind that packages uploaded there are not automatically processed, they
have to go through the hands of the release manager. So you'd better have a good
reason to upload there. In order to know what a good reason is in the
release manager's eyes, you should read the instructions that he regularly
gives on &email-debian-devel-announce;.
+ <p>
You should not upload to <em>testing-proposed-updates</em> when you can update your
packages through <em>unstable</em>. If you can't (for example because you have a
newer development version in unstable), you may use it but it is recommended to ask
the authorization of the release manager before.
- <sect1 id="uploading">Uploading a package
+ <sect id="upload">Uploading a package
- <sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
+ <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
<p>
To upload a package, you need a personal account on
<ftpsite>&ftp-master-host;</ftpsite>, which you should have as an
official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
to transfer the files, place them into &us-upload-dir;;
if you use anonymous FTP to upload, place them into
-&upload-queue;. Please note that you should transfer
+&upload-queue;.
+ <p>
+Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
all files have been uploaded. If you don't want to bother with transferring
<p>
After uploading your package, you can check how the archive
maintenance software will process it by running <prgn>dinstall</prgn>
-on your changes file: <example>dinstall -n foo.changes</example>.
+on your changes file:
+<example>dinstall -n foo.changes</example>
+ <p>
Note that <prgn>dput</prgn> can do this for you automatically.
- <sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
+ <sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
<p>
As discussed above, export controlled software should not be uploaded
to <tt>ftp-master</tt>. Instead, upload the package to
residents consult a lawyer before doing uploads to non-US.
- <sect2>Uploads via <tt>chiark</tt>
+ <sect1>Uploads via <tt>chiark</tt>
<p>
If you have a slow network connection to <tt>ftp-master</tt>, there are
alternatives. One is to upload files to <file>Incoming</file> via a
program for details.
- <sect2>Uploads via <tt>erlangen</tt>
+ <sect1>Uploads via <tt>erlangen</tt>
<p>
Another upload queue is available in Germany: just upload the files
via anonymous FTP to <url id="&url-upload-erlangen;">.
the program for details.
- <sect2>Other upload queues
+ <sect1>Other upload queues
<p>
Another upload queue is available which is based in the US, and is a
good backup when there are problems reaching <tt>ftp-master</tt>. You can
The installation notification also includes information on what
section the package was inserted into. If there is a disparity, you
will receive a separate email notifying you of that. Read on below.
+ <p>
+Note also that if you upload via queues, the queue daemon software will
+also send you a notification by email.
- <sect1 id="override-file">Determining section and priority of a package
+ <sect id="override-file">Determining section and priority of a package
+ <p>
The <file>debian/control</file> file's <tt>Section</tt> and
<tt>Priority</tt> fields do not actually specify where the file will
be placed in the archive, nor its priority. In order to retain the
overall integrity of the archive, it is the archive maintainers who
have control over these fields. The values in the
<file>debian/control</file> file are actually just hints.
+ <p>
The archive maintainers keep track of the canonical sections and
priorities for packages in the <em>override file</em>. If there is a
disparity between the <em>override file</em> and the package's fields
archive. You can either correct your <file>debian/control</file> file
for your next upload, or else you may wish to make a change in the
<em>override file</em>.
+ <p>
To alter the actual section that a package is put in, you need to
first make sure that the <file>debian/control</file> in your package
is accurate. Next, send an email &email-override; or submit a bug
against <package>ftp.debian.org</package> requesting that the section
or priority for your package be changed from the old section or
priority to the new one. Be sure to explain your reasoning.
+ <p>
For more information about <em>override files</em>, see <manref
name="dpkg-scanpackages" section="8"> and
<url id="&url-bts-devel;#maintincorrect">.
to do this. Some information on filing bugs can be found in <ref
id="submit-bug">.
- <sect1>Monitoring bugs
+ <sect1 id="bug-monitoring">Monitoring bugs
<p>
If you want to be a good maintainer, you should periodically check the
<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
<p>
Make sure that any discussion you have about bugs are sent both to
the original submitter of the bug, and the bug itself (e.g.,
-<email>123@bugs.debian.org</email>). If you're writing a new
+<email>123@&bugs-host;</email>). If you're writing a new
mail and you don't remember the submitter email address, you can
-use the <email>123-submitter@bugs.debian.org</email> email to
+use the <email>123-submitter@&bugs-host;</email> email to
contact the submitter <em>and</em> to record your mail within the
bug log (that means you don't need to send a copy of the mail to
-<email>123@bugs.debian.org</email>).
+<email>123@&bugs-host;</email>).
<p>
Once you've dealt with a bug report (e.g. fixed it), mark it as
<em>done</em> (close it) by sending an explanation message to
-<email>123-done@bugs.debian.org</email>. If you're fixing a bug by
+<email>123-done@&bugs-host;</email>. If you're fixing a bug by
changing and uploading the package, you can automate bug closing as
described in <ref id="upload-bugfix">.
<p>
are described in the <url id="&url-bts-devel;" name="BTS documentation for
Debian developers">. Operations such as reassigning, merging, and tagging
bug reports are described in the <url id="&url-bts-control;" name="BTS
-control bot documentation">. This section contains
+control server documentation">. This section contains
some guidelines for managing your own bugs, based on the collective
Debian developer experience.
<p>
<sect1 id="upload-bugfix">When bugs are closed by new uploads
<p>
-If you fix a bug in your packages, it is your responsibility as the
-package maintainer to close the bug when it has been fixed. However,
+As bugs and problems are fixed your packages, it is your
+responsibility as the package maintainer to close the bug. However,
you should not close the bug until the package which fixes the bug has
been accepted into the Debian archive. Therefore, once you get
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
<p>
However, it's possible to avoid having to manually close bugs after the
-upload -- just list the fixed bugs in your <file>debian/changelog</file>
+upload — just list the fixed bugs in your <file>debian/changelog</file>
file, following a certain syntax, and the archive maintenance software
will close the bugs for you. For example:
* Added man page. Closes: #98725.
</example>
-Technically speaking, the following Perl regular expression is what is
-used:
+Technically speaking, the following Perl regular expression describes
+how bug closing changelogs are identified:
<example>
/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
</example>
-The author prefers the <tt>closes: #<var>XXX</var></tt> syntax, as
-one of the most concise and easiest to integrate with the text of the
+We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the
+most concise entry and the easiest to integrate with the text of the
<file>changelog</file>.
<p>
-If you happen to mistype a bug number or forget one in the changelog file,
-don't hesitate to undo any damage the error caused. To reopen wrongly closed
-bugs, send an <tt>reopen <var>XXX</var></tt> command in the bug tracking
-system's control bot. To close any remaining bugs that were fixed by your
-upload, email the <file>.changes</file> file to
-<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
-bug number.
- <p>
-Bear in mind that it is not obligatory to close bugs using the changelog
-like described above -- if you simply want to close bugs that don't have
-anything to do with an upload of yours, do it simply by emailing an
-explanation to <email>XXX-done@bugs.debian.org</email>.
-Do <strong>not</strong> close bugs in the changelog entry of a version
-if the said version of the package doesn't have anything to do with the bug.
+If you happen to mistype a bug number or forget a bug in the changelog
+entries, don't hesitate to undo any damage the error caused. To reopen
+wrongly closed bugs, send an <tt>reopen <var>XXX</var></tt> command to
+the bug tracking system's control address, &email-bts-control;. To
+close any remaining bugs that were fixed by your upload, email the
+<file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,
+where <var>XXX</var> is your bug number.
+ <p>
+Bear in mind that it is not obligatory to close bugs using the
+changelog as described above. If you simply want to close bugs that
+don't have anything to do with an upload you made, do it by emailing
+an explanation to <email>XXX-done@&bugs-host;</email>. Do
+<strong>not</strong> close bugs in the changelog entry of a version if
+the changes in that version of the package doesn't have any bearing on
+the bug.
+ <p>
+For general information on how to write your changelog entries, see
+<ref id="bpp-debian-changelog">.
+
<sect1 id="bug-security">Handling security-related bugs
<p>
Review and test your changes as much as possible. Check the
differences from the previous version repeatedly
(<prgn>interdiff</prgn> from the <package>patchutils</package> package
-and <prgn>debdiff</prgn> from <package>devscripts</package> are useful tools for
-this).
-
+and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
+tools for this, see <ref id="debdiff">).
+<p>
When packaging the fix, keep the following points in mind:
<list>
<tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
are set properly. The best way to validate this is to use the
<package>debootstrap</package> package to create an unstable chroot
-environment. Within that chrooted environment, install the
+environment (see <ref id="debootstrap">).
+Within that chrooted environment, install the
<package>build-essential</package> package and any package
dependencies mentioned in <tt>Build-Depends</tt> and/or
<tt>Build-Depends-Indep</tt>. Finally, try building your package
within that chrooted environment. These steps can be automated
by the use of the <prgn>pbuilder</prgn> program which is provided by
-the package of the same name.
+the package of the same name (see <ref id="pbuilder">).
+ <p>
+If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
+of assistance (see <ref id="dpkg-depcheck">).
<p>
See the <url id="&url-debian-policy;" name="Debian Policy
Manual"> for instructions on setting build dependencies.
Wait a few more days. If you still haven't got an answer from the
maintainer, send him a mail announcing your intent to NMU the package.
Prepare an NMU as described in <ref id="nmu-guidelines">, test it
-carefully on your machine (cf. <ref id="upload-checking">).
+carefully on your machine (cf. <ref id="sanitycheck">).
Double check that your patch doesn't have any unexpected side effects.
Make sure your patch is as small and as non-disruptive as it can be.
<item>
<sect2 id="nmu-build">Building source NMUs
<p>
Source NMU packages are built normally. Pick a distribution using the
-same rules as found in <ref id="upload-dist">. Just as described in
-<ref id="uploading">, a normal changes file, etc., will be built. In
-fact, all the prescriptions from <ref id="upload"> apply.
+same rules as found in <ref id="distribution">, follow the other
+prescriptions in <ref id="upload">.
<p>
Make sure you do <em>not</em> change the value of the maintainer in
the <file>debian/control</file> file. Your name as given in the NMU entry of
<sect id="bpp-debian-control">
<heading>Best practices for <file>debian/control</file></heading>
<p>
-The following practices supplement the <url
- id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
- name="Policy on package descriptions">.</p>
+The following practices are relevant to the
+<file>debian/control</file> file. They supplement the <url
+id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+name="Policy on package descriptions">.
+ <p>
+The description of the package, as defined by the corresponding field
+in the <file>control</file> file, contains both the package synopsis
+and the long description for the package.
+
+
+
+ <sect1 id="bpp-desc-basics">
+ <heading>General guidelines for package descriptions</heading>
+ <p>
+The package description should be written for the average likely user,
+the average person who will use and benefit from the package. For
+instance, development packages are for developers, and can be
+technical in their language. More general-purpose applications, such
+as editors, should be written for a less technical user.
+ <p>
+Our review of package descriptions lead us to conclude that most
+package descriptions are technical, that is, are not written to make
+sense for non-technical users. Unless your package really is only for
+technical users, this is a problem.
+ <p>
+How do you write for non-technical users? Avoid jargon. Avoid
+referring to other applications or frameworks that the user might not
+be familiar with — "GNOME" or "KDE" is fine, but "GTK+" is
+probably not. Try not to assume any knowledge at all. If you must
+use technical terms, introduce them.
+ <p>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one
+exists. For example, use "X Window System", "X11", or "X"; not "X
+Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
+Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or
+"postscript".
+
+
+ <sect1 id="bpp-pkg-synopsis">
+ <heading>The package synopsis, or short description</heading>
+ <p>
+The synopsis line (the short description) should be concise. It
+must not repeat the package's name (this is policy).
+ <p>
+It's a good idea to think of the synopsis as an appositive clause, not
+a full sentence. An appositive clause is defined in WordNet as a
+grammatical relation between a word and a noun phrase that follows,
+e.g., "Rudolph the red-nosed reindeer". The appositive clause here is
+"red-nosed reindeer". Since the synopsis is a clause, rather than a
+full sentence, we recommend that it neither start with a capital nor
+end with a full stop (period). Imagine that the synopsis is combined
+with the package name in the following way:
+
+<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+ <p>
+If the package name is an acronym, it is sometimes useful to expand
+the acronym. For instance, the synopsis for <package>vim</package> is
+"Vi IMproved - enhanced vi editor".
+
<sect1 id="bpp-pkg-desc">
- <heading>Writing useful descriptions</heading>
+ <heading>The long description</heading>
+ <p>
+The long description is the primary information available to the user
+about a package before they install it. It should provide all the
+information needed to let the user decide whether to install the
+package. Assume that the user has already read the package synopsis.
<p>
-The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is the primary information available
-to the user about a package before they install it. It should provide
-all the required information to let the user decide whether to install
-the package.
+The long description should consist of full and complete sentences.
+It is recommended to use two spaces after full stops in sentences. We
+realize this is an American style rather than European, but it is
+additionally helpful in creating visual space in fixed-width fonts.
<p>
-For consistency and aesthetics, you should capitalize the first letter
-of the Synopsis. Don't put a full stop (period) at the end. The
-description itself should consist of full sentences.
+The first paragraph of the long description should answer the
+following questions: what does the package do? what task does it help
+the user accomplish? It is important to describe this in a
+non-technical way, unless of course the audience for the package is
+necessarily technical.
<p>
-Since the first user impression is based on the description, be
-careful to avoid spelling and grammar mistakes. Ensure that you
+The following paragraphs should answer the following questions: Why do
+I as a user need this package? What other features does the package
+have? What outstanding features and deficiencies are there compared
+to other packages (e.g., "if you need X, use Y instead")? Is this
+package related to other packages in some way that is not handled by
+the package manager (e.g., "this is the client to the foo server")?
+ <p>
+Be careful to avoid spelling and grammar mistakes. Ensure that you
spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
for <file>debian/control</file> files:
<example>ispell -d american -g debian/control</example>
-If you want someone to proofread the description that you
-intend to use you may ask on &email-debian-l10n-english;.
</sect1>
<sect1 id="bpp-upstream-info">
</sect1>
</sect>
+
+ <sect id="bpp-debian-changelog">
+ <heading>Best practices for <file>debian/changelog</file></heading>
+ <p>
+The following practices supplement the <url name="Policy on changelog
+files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
+
+ <sect1 id="bpp-changelog-do">
+ <heading>Writing useful changelog entries</heading>
+ <p>
+The changelog entry for a package revision documents changes in that
+revision, and only them. Concentrate on describing significant and
+user-visible changes that were made since the last version.
+ <p>
+Focus on <em>what</em> was changed — who, how and when are
+usually less important. Having said that, remember to politely
+attribute people who have provided notable help in making the package
+(e.g., those who have sent in patches).
+ <p>
+There's no need to elaborate the trivial and obvious changes. You can
+also aggregate several changes in one entry. On the other hand, don't
+be overly terse if you have undertaken a major change. Be especially
+clear if there are changes that affect the behaviour of the program.
+For further explanations, use the <file>README.Debian</file> file.
+ <p>
+Use common English so that the majority of readers can comprehend it.
+Avoid abbreviations, "tech-speak" and jargon when explaining changes
+that close bugs, especially for bugs filed by users that did not
+strike you as particularly technically savvy. Be polite, don't swear.
+ <p>
+It is sometimes desirable to prefix changelog entries with the names
+of the files that were changed. However, there's no need to
+explicitly list each and every last one of the changed files,
+especially if the change was small or repetitive. You may use
+wildcards.
+ <p>
+When referring to bugs, don't assume anything. Say what the problem
+was, how it was fixed, and append the "closes: #nnnnn" string. See
+<ref id="upload-bugfix"> for more information.
+
+
+ <sect1 id="bpp-changelog-misconceptions">
+ <heading>Common misconceptions about changelog entries</heading>
+ <p>
+The changelog entries should <strong>not</strong> document generic
+packaging issues ("Hey, if you're looking for foo.conf, it's in
+/etc/blah/."), since administrators and users are supposed to be at
+least remotely acquainted with how such things are generally arranged
+on Debian systems. Do, however, mention if you change the location of
+a configuration file.
+ <p>
+The only bugs closed with a changelog entry should be those that are
+actually fixed in the same package revision. Closing unrelated bugs
+in the changelog is bad practice. See <ref id="upload-bugfix">.
+ <p>
+The changelog entries should <strong>not</strong> be used for random
+discussion with bug reporters ("I don't see segfaults when starting
+foo with option bar; send in more info"), general statements on life,
+the universe and everything ("sorry this upload took me so long, but I
+caught the flu"), or pleas for help ("the bug list on this package is
+huge, please lend me a hand"). Such things usually won't be noticed
+by their target audience, but may annoy people who wish to read
+information about actual changes in the package. See <ref
+id="bug-answering"> for more information on how to use the bug
+tracking system.
+ <p>
+It is an old tradition to acknowledge bugs fixed in non-maintainer
+uploads in the first changelog entry of the proper maintainer upload,
+for instance, in a changelog entry like this:
+<example>
+ * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+This will close the NMU bugs tagged "fixed" when the package makes
+it into the archive. The bug for the fact that an NMU was done can be
+closed the same way. Of course, it's also perfectly acceptable to
+close NMU-fixed bugs by other means; see <ref id="bug-answering">.
+ </sect1>
+
+ <sect1 id="bpp-changelog-errors">
+ <heading>Common errors in changelog entries</heading>
+ <p>
+The following examples demonstrate some common errors or example of
+bad style in changelog entries.
+
+ <p>
+<example>
+ * Fixed all outstanding bugs.
+</example>
+This doesn't tell readers anything too useful, obviously.
+
+ <p>
+<example>
+ * Applied patch from Jane Random.
+</example>
+What was the patch about?
+
+ <p>
+<example>
+ * Late night install target overhaul.
+</example>
+Overhaul which accomplished what? Is the mention of late night
+supposed to remind us that we shouldn't trust that code?
+
+ <p>
+<example>
+ * Fix vsync FU w/ ancient CRTs.
+</example>
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
+a curse word!) was actually about, or how it was fixed.
+
+ <p>
+<example>
+ * This is not a bug, closes: #nnnnnn.
+</example>
+First of all, there's absolutely no need to upload the package to
+convey this information; instead, use the bug tracking system.
+Secondly, there's no explanation as to why the report is not a bug.
+
+ <p>
+<example>
+ * Has been fixed for ages, but I forgot to close; closes: #54321.
+</example>
+If for some reason you didn't mention the bug number in a previous changelog
+entry, there's no problem, just close the bug normally in the BTS. There's
+no need to touch the changelog file, presuming the description of the fix is
+already in (this applies to the fixes by the upstream authors/maintainers as
+well, you don't have to track bugs that they fixed ages ago in your
+changelog).
+
+ <p>
+<example>
+ * Closes: #12345, #12346, #15432
+</example>
+Where's the description? If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+ </sect1>
+ </sect>
+
<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
<p>
sympa may be an example package
-->
- <sect1 id="bpp-archindepdata">Architecture-independent data
- <p>
- It is not uncommon to have a large amount of architecture-independent
- data packaged with a program. For example, collection of icons,
- wallpapers or other graphic files, or audio files. If the size of
- this data is negligible compared to the size of the remainder of the
- package, you can keep it all in the same package.
-
- <p>
- However, if the size of the data is considerable, consider splitting
- it out into a separate, architecture-independent package
- ("_all.deb"). By doing this, you avoid needless duplication of the
- same data into eleven or more .debs per each architecture. While
- this adds some extra overhead into the Packages files, it can save a
- lot of disk space on Debian mirrors, and it also reduces processing
- time of Lintian or Linda when run over the entire Debian archive.
- </sect1>
-
+ <sect1 id="bpp-archindepdata">
+ <heading>Architecture-independent data</heading>
+ <p>
+It is not uncommon to have a large amount of architecture-independent
+data packaged with a program. For example, audio files, a collection
+of icons, wallpaper patterns, or other graphic files. If the size of
+this data is negligible compared to the size of the rest of the
+package, it's probably best to keep it all in a single package.
+ <p>
+However, if the size of the data is considerable, consider splitting
+it out into a separate, architecture-independent package ("_all.deb").
+By doing this, you avoid needless duplication of the same data into
+eleven or more .debs, one per each architecture. While this
+adds some extra overhead into the <file>Packages</file> files, it
+saves a lot of disk space on Debian mirrors. Separating out
+architecture-independent data also reduces processing time of
+<prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)
+when run over the entire Debian archive.
+ </sect1>
</sect>
+ </chapt>
+
<chapt id="beyond-pkging">
<heading>Beyond Packaging</heading>
filing the same bug report simultaneously.
<p>
Note that when sending lots of bugs on the same subject, you should
-send the bug report to <email>maintonly@bugs.debian.org</email> so
+send the bug report to <email>maintonly@&bugs-host;</email> so
that the bug report is not forwarded to the bug distribution mailing
list.
before uploading it to the incoming directory.
<p>
The Maintainer field of the <file>control</file> file and the
-<file>changelog</file> should list the person who did the packaging, i.e. the
+<file>changelog</file> should list the person who did the packaging, i.e., the
sponsoree. The sponsoree will therefore get all the BTS mail about the
package.
<p>
option provides detailed explanations of what each error or warning means,
what is its basis in Policy, and commonly how you can fix the problem.
<p>
-Refer to <ref id="upload-checking"> for more information on how and when
+Refer to <ref id="sanitycheck"> for more information on how and when
to use Lintian.
<p>
You can also see a summary of all problems reported by Lintian on your
<package>lintian</package> but has a different set of checks. Its
written in Python rather than Perl.</p>
</sect1>
+
+ <sect1 id="debdiff">
+ <heading><package>debdiff</package></heading>
+ <p>
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)
+compares file lists and control files of two packages. It is a simple
+regression test, as it will help you notice if the number of binary
+packages has changed since the last upload, or if something's changed
+in the control file. Of course, some of the changes it reports will be
+all right, but it can help you prevent various accidents.
+ <p>
+You can run it over a pair of binary packages:
+<example>
+debdiff package_1-1_arch.deb package_2-1_arch.deb
+</example>
+ <p>
+Or even a pair of changes files:
+<example>
+debdiff package_1-1_arch.changes package_2-1_arch.changes
+</example>
+ <p>
+For more information please see <manref name="debdiff" section="1">.
+ </sect1>
+
</sect>
+
<sect id="tools-helpers">
<heading>Helpers for <file>debian/rules</file></heading>
<p>
<file>debian/changelog</file>, there are handy functions for
finalizing a version and listing the package's current bugs.</p>
</sect1>
+
+ <sect1 id="dpkg-depcheck">
+ <heading><package>dpkg-depcheck</package></heading>
+ <p>
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package>
+package, <ref id="devscripts">)
+runs a command under <prgn>strace</prgn> to determine all the packages that
+were used by the said command.
+ <p>
+For Debian packages, this is useful when you have to compose a
+<tt>Build-Depends</tt> line for your new package: running the build
+process through <prgn>dpkg-depcheck</prgn> will provide you with a
+good first approximation of the build-dependencies. For example:
+<example>
+dpkg-depcheck -b debian/rules build
+</example>
+ <p>
+<prgn>dpkg-depcheck</prgn> can also be used to check for run-time
+dependencies, especially if your package uses exec(2) to run other
+programs.
+ <p>
+For more information please see <manref name="dpkg-depcheck" section="1">.
+ </sect1>
+
</sect>
~ianmdlvl / developers-reference.git / blobdiff