dpkg/doc/policy.sgml

<!doctype debiandoc system [
<!entity % manuals-version-def system "manuals-version">
%manuals-version-def;
]>

<!--
 Debian Linux package policy manual.
 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
 General Public License, version 2 or (at your option) any later.
 -->

<book>

<title>Debian policy manual
<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
<version>version &manuals-version; (dpkg &dpkg-version;), <date>

<abstract>
This manual describes the policy requirements which must be satisfied
for a package to be included in the Debian distribution.  This
includes details of the permissions and ownerships of files in
packages and other technical requirements as well as information like
the upload procedure.
</abstract>

<copyright>Copyright &copy;1996 Ian Jackson.
<p>

This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
<p>

This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose.  See the GNU
General Public License for more details.
<p>

You should have received a copy of the GNU General Public License with
your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>.  If
not, write to the Free Software Foundation, Inc., 675 Mass Ave,
Cambridge, MA 02139, USA.

<toc sect>

<chapt id="scope">Introduction and scope of this manual
<p>

This manual describes the criteria that a Debian-format package must
satisfy to be included in the Debian distribution.
<p>

Much of this information will be useful even when building a package
which is to be distributed in some other way or is for local use.
<p>

This manual does <em/not/ describe the technical mechanisms involved
in package creation, installation and removal.  This information can
be found in the <prgn/dpkg/ programmers' manual and the <prgn/dpkg/ system
administrators' manual.
<p>

This document assumes familiarity with these other two manuals.
Unfortunately the system administrators' manual does not exist yet.
<p>

The Debian version of the FSF's GNU <prgn/hello/ program is provided
as an example for people wishing to create Debian packages.
<p>

<em>Note that this document is still a draft!</em>

<chapt id="pkgcopyright">Package copyright
<p>

Please study the copyright of your submission <em/carefully/ and
understand it before proceeding.  If you have doubts or questions,
please ask.
<p>

The aims of the policy detailed below are:
<list compact>
<item>
That any user be able to rebuild any package in the official Debian
distribution from the original source plus our patches.
<item>
That we make available in our packaging formats as much software as we
can.
<item>
That it be easy for people to make CDROMs of our distribution without
violating copyrights.
</list>
<p>

All packages in the Debian distribution proper must be freely useable,
modifiable and redistributable in both source and binary
form.<footnote>It is OK for there to be a requirement that modified
versions carry a warning, or that they be released with a different
name or version number, or something similar, because we can comply
with this requirement if necessary.</footnote>
It must be possible for anyone to distribute and use modified source
code and their own compiled binaries, at least when they do so as part
of a Debian distribution.
<p>

Packages
<list compact>
<item>
whose copyright permission notices (or patent problems) do not allow
distribution and copying for profit, without restriction on the amount
charged, or
<item>
where distribution is restricted according to the medium used, or
<item>
where the distributor must ask any kind of special permission of the
authors, or
<item>
with other onerous conditions,
</list>
may only be placed in the semi-supported non-free section of the
Debian FTP archives.  This is important so that CDROM manufacturers
can distribute Debian without having to check the copyright of each
package individually, simply by leaving out the contents of the
non-free area; CDROM distributors are encouraged, though, to check the
copyrights on programs in non-free individually and include as many as
they can.
<p>

Packages
<list compact>
<item>
whose copyright permission notices (or patent problems) allow only
distribution of compiled binaries (and thus of which only binaries are
available), or
<item>
where the source code which may be
distributed is not the complete source code required to compile the
program (ie, the program cannot be compiled using only packages in the
main Debian distribution), or
<item>
which depend for their use on non-free or contrib packages, or
<item>
allow free use only for a trial period (shareware), or
<item>
are demonstration programs lacking vital functionality (crippleware),
or
<item>
are only installer-packages which require the user to supply a
separate file to be installed, or
<item>
which fail to meet some other policy requirements,
</list>
may only be placed in the semi-supported contrib section of the Debian
FTP archives (unless they need to be in non-free - see above).
<p>

Programs whose authors encourage the user to make donations are fine
for the main distribution, provided that the authors do not claim that
not donating is immoral, unethical, illegal or something similar;
otherwise they must go in contrib (or non-free, if even distribution
is restricted by such statements).
<p>

Packages whose copyright permission notices (or patent problems) do
not allow redistribution even of only binaries, and where no special
permission has been obtained, cannot placed on the Debian FTP site and
its mirrors at all.
<p>

Note that under international copyright law<footnote>This applies in
the United States, too.</footnote> <em/no/ distribution or modification
of a work is allowed without an explicit notice saying so.  Therefore
a program without a copyright notice <em/is/ copyrighted and you may
not do anything to it without risking being sued!  Likewise if a
program has a copyright notice but no statement saying what is
permitted then nothing is permitted.
<p>

Many authors are unaware of the problems that restrictive copyrights
(or lack of copyright notices) can cause for the users of their
supposedly-free software.  It is often worthwhile contacting such
authors diplomatically to ask them to modify their terms generally, or
specially for Debian.  However, this is a politically difficult thing
to do and you should ask for advice on <prgn/debian-devel/ first.
<p>

When in doubt, send mail to <email/debian-devel@lists.debian.org/.  Be
prepared to provide us with the copyright statement.  Software covered
by the GPL, public domain software and BSD-like copyrights are safe;
be wary of the phrases `commercial use prohibited' and `distribution
restricted'.
<p>

Every package submission <em/must/ be accompanied by verbatim copy of
its copyright (with the exceptions of public domain packages and those
covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases
simply indicate which is appropriate).  This information must be
included in a file installed by the binary package - see <ref
id="copyrightfile">.

<chapt id="binarypkg">Contents of the binary package

<sect>Control file requirements

<sect1><tt/Maintainer/ information
<p>

All packages must have a <tt/Maintainer/ field with the correct name
and a working email address for the Debian maintainer of the package.
If one person maintains several packages they should try to avoid
having different forms of their name and address in different
<tt/Maintainer/ fields.

<sect1>Dependencies and virtual packages
<p>

Add a dependency for any shared libraries required by
dynamically-linked executable binaries in your package.  Almost every
package containing compiled C code should therefore include a
<tt/Depends/ field which mentions the shared C library required for
the program to run.  For ELF binaries linked against <tt/libc.so.5/
the relevant package name is <tt/libc5/.
<p>

All packages must use virtual package names where appropriate, and
arrange to create new ones if necessary.  They must not use virtual
package names (except privately, amongst a cooperating group of
packages) unless they have been agreed upon and appear in the list of
virtual package names.
<p>

The latest version of the authoritative list of virtual package names
can be found on <ftpsite>ftp.debian.org</> in
<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
or your local mirror.  The procedure for updating it is described at
the top of the file.

<sect1><tt/Section/ and <tt/Priority/
<p>

Decide whether your package can go in <tt/non-free/, <tt/contrib/ or
the main distribution - see <ref id="pkgcopyright">, and put
an appropriate value for the distribution in the
<tt>debian/changelog</> file.
<p>

The <tt/Priority/ and <tt/Section/ control file fields give
information for classifying the package in <prgn/dselect/ and say
which directory to place it in the FTP archive.
<p>

They are ultimately the responsibility of the distribution
maintainers; however, you should suggest values for them in your
<tt/.changes/ information when you upload a package.  You do this by
including appropriate information in the <tt>debian/control</tt> file
before building the packages.
<p>

For a list of the currently in-use sections, please see the FTP
archive.  Packages in the non-free and contrib areas should have
section <tt/non-free/ and <tt/contrib/, respectively.

<sect2><tt/Priority/ values
<p>

<taglist>
<tag><tt/required/
<item>
<tt/required/ packages are necessary for the proper functioning of the
system.  You must not remove these packages or your system may become
totally broken and you may probably not even be able to use
<prgn/dpkg/ to put things back.  Systems with only the <tt/required/
packages are probably unuseable, but they do have enough functionality
to allow the sysadmin to boot and install more software.

<tag><tt/important/
<item>
Important programs, including those which one would expect to find on
any Unix-like system.  If the expectation is that an experienced Unix
person who found it missing would go `What the F*!@&lt;+ is going on,
where is <prgn/foo/', it should be in <tt/important/.  This is an
important criterion because we are trying to produce, amongst other
things, a free Unix.  Other packages without which the system will not
run well or be useable should also be here.  This does <em/not/
include Emacs or X11 or TeX or any other large applications.  The
<tt/important/ packages are just a bare minimum of commonly-expected
and necessary tools.

<tag><tt/standard/
<item>
These packages provide a reasonably small but not too limited
character-mode system.  This is what will install by default if the
user doesn't select anything else.  It doesn't include many large
applications, but it does include Emacs (this is more of a piece of
infrastructure than an application) and a reasonable subset of TeX and
LaTeX (if this is possible without X).

<tag><tt/optional/<footnote>In a sense everything is optional that
isn't required, but that's not what is meant here.</footnote>
<item>
This is all the software that you might reasonably want to install if
you didn't know what it was or don't have specialised requirements.
This is a much larger system and includes X11, a full TeX
distribution, and lots of applications.

<tag><tt/extra/
<item>
This contains packages that conflict with others with higher
priorities, or are only likely to be useful if you already know what
they are or have specialised requirements.

</taglist>
<p>

Priority values are not case-sensitive.

<sect2>Base packages
<p>

Some packages have <tt/Section: base/ and are in the <tt/base/
subdirectory on the FTP archives.  These are the packages that are
supplied on the base disks.  They are the minimum sensible set for
installing new packages (perhaps via a network).
<p>

Most of these packages should have <tt/Priority: required/ or at least
<tt/Priority: important/.

<sect1>The <tt/Essential/ flag
<p>

The <tt/Essential: yes/ control file field should not be used unless
removing a package really will completely hose the system; nor should
it be used for a shared library package - the dependencies will
prevent its premature removal, and we need to be able to remove it
when it has been superseded.

<sect1>Including <tt/Priority/ and <tt/Section/ in the <tt/.deb/
control file
<p>

If a user installs a package which is not part of the standard
distribution, or without downloading and updating from a new
<prgn/Packages/ file, the information about the priority and section
of a package will be absent, and the <prgn/dselect/ package listing
will have the package listed under `unclassified'.  In order to
improve this it is permissible to use the <tt/-is/, <tt/-isp/ or
<tt/-ip/ option to <prgn/dpkg-gencontrol/, so that the <tt/Section/
and/or <tt/Priority/ is copied into the actual control information in
the <tt/.deb/ file.  However, if you do this you should make sure you
keep the information up to date so that users are not shown
conflicting information.


<sect1>Formatting of the <tt/Description/ control file field
<p>

Every Debian package should have an extended description.
<p>

The description should be written so that it tells the user what they
need to know to decide whether to install the package.  This
description should not just be copied from the blurb for the program.
Instructions for configuring or using the package should not be
included - that is what installation scripts, manpages, Info files and
<tt>/usr/doc/<var/package/</> are for.  Copyright statements and other
administrivia should not be included - that is what
<tt>/usr/doc/<var/package//copyright</> is for.
<p>

If you wish to include a list in your extended with entries which are
a line or more each you must indent each entry by one space to make
sure that it doesn't get wordwrapped.  The start of each list entry
should be marked with an asterisk, followed by a single space.  You
must wrap the list entries yourself to 75 columns, and should start
continuation lines indented by three spaces so that they line up with
the start of the text on the first line of each list entry.
<p>

See the programmers' manual for further requirements and pitfalls.

<sect>Locations of files
<p>

The location of all installed files and directories must comply fully
with the Linux File System Standard (FSSTND).  The latest version of
this document can be found alongside this manual or on
<ftpsite/tsx-11.mit.edu/ in
<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>.  Specific questions
about following the standard may be asked on <prgn/debian-devel/, or
referred to Daniel Quinlan, the FSSTND coordinator, at
<email/quinlan@yggdrasil.com/.
<p>

<sect1>Manpages
<p>

You must install manpages in <prgn/nroff/ source form, in appropriate
places under <tt>/usr/man</tt>.  You should only use sections 1 to 9
(see the FSSTND for more details).  You must <em/not/ install a
preformatted `cat page'.
<p>

If no manual page is available for a particular program, utility or
function and this is reported as a bug on debian-bugs, a symbolic link
from the requested manual page to the <manref name=undocumented
section=7> manual page should be provided.  This symbolic link can be
created from <tt>debian/rules</> like this:
<example>
ln -s ../man7/undocumented.7 \
 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
</example>
This manpage claims that the lack of a manpage has been reported as a
bug, so you may only do this if it really has (you can report it
yourself, if you like).  Do not close the bug report until a proper
manpage is available.
<p>

You may forward a complaint about a missing manpage to the upstream
authors, and mark the bug as forwarded in the Debian bug tracking
system.  Even though the GNU Project do not in general consider the
lack of a manpage to be a bug, we do - if they tell you that they
don't consider it a bug you should leave the bug in our bug tracking
system open anyway.
<p>

Manpages should be installed compressed using <tt/gzip -9/.
<p>

If one manpage needs to be accesssible via several names it is better
to use a symbolic link than the <tt/.so/ feature, but there is no need
to fiddle with the relevant parts of the upstream source to change
from <tt/.so/ to symlinks - don't do it unless it's easy.  Do not
create hard links in the manual page directories, and do not put
absolute filenames in <tt/.so/ directives.  The filename in a
<tt/.so/ in a manpage should be relative to the base of the manpage
tree (usually <tt>/usr/man</tt>).

<sect1>Info documents
<p>

Info documents should be installed in <tt>/usr/info</tt>.  They should
be compressed with <tt/gzip -9/.
<p>

Your package must call <prgn/install-info/ to update the Info <tt/dir/
file, in its post-installation script:
<example>
install-info --quiet --section Development Development \
  /usr/info/foobar.info
</example>
<p>

It is a good idea to specify a section for the location of your
program; this is done with the <tt/--section/ switch.  To determine
which section to use, you should use look at <tt>/usr/info/dir</> on
your system and choose the most relevant (or create a new section if
none of the current sections are relevant).  Note that the
<tt/--section/ flag takes two arguments; the first is a regular
expression to match (case-insensitively) against an existing section,
the second is used when creating a new one.
<p>

You must remove the entries in the pre-removal script:
<example>
install-info --quiet --remove /usr/info/foobar.info
</example>
<p>

If <prgn/install-info/ cannot find a description entry in the Info file
you will have to supply one.  See <manref name=install-info section=8>
for details.

<sect1>Additional documentation
<p>

Any additional documentation that comes with the package can be
installed at the discretion of the package maintainer.  Text
documentation should be installed in a directory
<tt>/usr/doc/<var/package/</tt><footnote>Where <var/package/ is the
name of the package.</footnote> and compressed with <tt/gzip -9/
unless it is small.
<p>

If a package comes with large amounts of documentation which many
users of the package will not require you should create a separate
binary package to contain it, so that it does not take up disk space
on the machines of users who do not need or want it installed.
<p>

It is often a good idea to put text information files (<tt/README/s,
changelogs, and so forth) that come with the source package in
<tt>/usr/doc/<var/package/</> in the binary package.  However, don't
install the instructions for building and installing the package, of
course!

<sect1>Preferred documentation formats
<p>

The unification of Debian documentation is being carried out via HTML.
<p>

If your package comes with extensive documentation in a markup format
that can be converted to various other formats you should if possible
ship HTML versions in the binary package, in the directory
<tt>/usr/doc/<var/package/</> or its subdirectories.
<p>

Other formats such as PostScript may be provided at your option.

<sect2>Examples
<p>

Any examples (configurations, source files, whatever), should be
installed in a directory <tt>/usr/doc/<var/package//examples</tt>.
These files should not be referenced by any program - they're there
for the benefit of the system administrator and users, as
documentation only.

<sect1 id="instchangelog"><tt>/usr/doc/<var/package//changelog.Debian.gz</tt>
<p>

This installed file must contain a copy of the <tt>debian/changelog</>
file from your Debian source tree.
<p>

It should be installed compressed using <tt/gzip -9/, as it will
become large with time even if it starts out small.
<p>

If the package has only one changelog which is used both as the Debian
changelog and the upstream one because there is no separate upstream
maintainer then the changelog should usually be installed as
<tt>/usr/doc/<var/package//changelog.gz</> instead.

<sect1 id="copyrightfile"><tt>/usr/doc/<var/package//copyright</tt>
<p>

This file must contain details of the authorship and copyright of the
package.  It must say where the upstream sources (if any) were
obtained, and explain briefly what modifications were made in the
Debian version of the package compared to the upstream one.  It must
name the original authors of the package and the Debian maintainer(s)
who were involved with its creation.
<p>

It must contain the full text of the copyright notice and any
acknowledgements for the program and the licence terms under which the
program is distributed.  If the package is distributed under the GNU
General Public Licence, the GNU Library General Public Licence, the
Regents of the University of California at Berkeley (BSD) licence or
Larry Wall's Artistic Licence please say so instead of including a
copy of the licence.  The files <tt/BSD/, <tt/GPL/, <tt/LGPL/ and
<tt/Artistic/ are be available in <tt>/usr/doc/copyright</tt> for you
to refer to.
<p>

The copyright file should not be compressed unless it is very large.
<p>

Do not use the copyright file as a general <tt/README/ file.  If your
package has such a file it should be installed in
<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
other appropriate place.

<sect1>Symbolic links
<p>

Most symbolic links should be relative, not absolute.  Absolute links,
in general, cause problems when a file system is not mounted where it
"normally" resides (for example, when mounted via NFS).
<p>

In particular, symlinks from one part of <tt>/usr</tt> to another
should be relative.
<p>

In certain cases, however, relative links may cause more problems.
For example, links into <tt>/etc</tt> and <tt>/var</tt> should be
absolute.
<p>

Note that when creating a relative link using <prgn/ln/ it is not
necessary for the target of the link to exist relative to the working
directory you're running <prgn/ln/ from; nor is it necessary to change
directory to the directory where the link is to be made.  Simply
include the string that should appear as the target of the link (this
will be a pathname relative to the directory in which the link
resides) as the first argument to <prgn/ln/.
<p>

For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
like:
<example>
ln -fs gcc $(prefix)/bin/cc
ln -fs gcc debian/tmp/usr/bin/cc
ln -fs ../sbin/sendmail $(prefix)/bin/runq
ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
</example>

<sect1>Logfiles
<p>

Logfiles should usually be named
<tt>/var/log/<var/package/.log</tt>.  If you have many logfiles,
or need a separate directory for permissions reasons
(<tt>/var/log</tt> is writeable only by <tt/root/), you should usually
create a directory named <tt>/var/log/<var/package/</tt>.
<p>

Make sure that any logfiles are rotated occasionally using so that
they don't grow indefinitely; the best way to do this is to use
<prgn/savelog/ program in an <tt>/etc/cron.daily</>,
<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script.
<p>

Make sure that any logfiles are removed when the package is purged
(but not when it is only removed), by checking the argument to the
postrm script (see the programmer's manual for details).

<sect1><tt>/usr/local</> - for the use of the system administrator
<p>

As mandated by the FSSTND no package should place any files in
<tt>/usr/local</>, either by putting them in the filesystem archive to
be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
scripts.
<p>

Every package that searches a number of directories or files for
something (for example, looking for shared libraries in <tt>/lib</> or
<tt>/usr/lib</>) should search an appropriate directory in
<tt>/usr/local</> too.
<p>

In order that the system administrator may know where to place
additional files a package should create an empty directory in the
appropriate place in <tt>/usr/local</> by supplying it in the
filesystem archive for unpacking by <prgn/dpkg/.  The
<tt>/usr/local</> directory itself and all the subdirectories created
by the package should have permissions 2775 (group-writeable and
set-group-id) and be owned by <tt/root.staff/.
<p>

In the future it will be possible to tell <prgn/dpkg/ not to unpack
files matching certain patterns, so that system administrators who do
not wish these directories in <tt>/usr/local</> do not need to have
them.

<sect>Permissions and ownerships
<p>

The rules in this section are guidelines for general use.  If
necessary you may deviate from the details below.  However, if you do
so you must make sure that what is done is secure and you must try to
be as consistent as possible with the rest of the system.  You should
probably also discuss it on <prgn/debian-devel/ first.
<p>

Files should be owned by <tt/root.root/, and made writeable only by
the owner and universally readable (and executable, if appropriate).
<p>

Directories should be mode 755 or (for group-writability) mode 2775.
The ownership of the directory should be consistent with its mode -
if a directory is mode 2775, it should be owned by the group that
needs write access to it.
<p>

Setuid and setgid executables should be mode 4755 or 2755
respectively, and owned by the appropriate user or group.  They should
not be made unreadable (modes like 4711 or 2711 or even 4111); doing
so achieves no extra security, because anyone can find the binary in
the freely available Debian package - it is merely inconvenient.  For
the same reason you should not restrict read or execute permissions on
non-set-id executables.
<p>

Some setuid programs need to be restricted to particular sets of
users, using file permissions.  In this case they should be owned by
the uid to which they are set-id, and by the group which should be
allowed to execute them.  They should have mode 4754; there is no
point in making them unreadable to those users who must not be allowed
to execute them.
<p>

Do not arrange that the system administrator can only reconfigure the
package to correspond to their local security policy by changing the
permissions on a binary.  Ordinary files installed by <prgn/dpkg/ (as
opposed to conffiles and other similar objects) have their permissions
reset to the distributed permissions when the package is reinstalled.
Instead you should consider (for example) creating a group for people
allowed to use the program(s) and making any setuid executables
executable only by that group.
<p>

Shared libraries should be installed executable.

<sect>Configuration files
<p>

Any configuration files created or used by your package should reside
in <tt>/etc</tt>.  If there are several you should consider creating a
subdirectory named after your package.
<p>

It is almost certain that any file in <tt>/etc</tt> that is in your
package's filesystem archive should be listed in <prgn/dpkg/'s
<tt/conffiles/ control area file.  (See the <prgn/dpkg/ programmers'
manual).

<sect>Maintainer scripts
<p>

The package installation scripts should avoid producing output which
it is unnecessary for the user to see and should rely on <prgn/dpkg/ to
stave off boredom on the part of a user installing many packages.
This means, amongst other things, using the <tt/--quiet/ option on
<prgn/install-info/.
<p>

Packages should try to minimise the amount of prompting they need to
do, and they should ensure that the user will only every be asked each
question once.  This means that packages should try to use appropriate
shared configuration files (such as <tt>/etc/papersize</> and
<tt>/etc/news/server</>, rather than each prompting for their own
list of required pieces of information.
<p>

It also means that an upgrade should not ask the same questions again,
unless the user has used <tt/dpkg --purge/ to remove the package's
configuration.  The answers to configuration questions should be
stored in an appropriate place in <tt>/etc</> so that the user can
modify them, and how this has been done should be documented.
<p>

If a package has a vitally important piece of information to pass to
the user (such as "don't run me as I am, you must edit the following
configuration files first or you risk your system emitting
badly-formatted messages"), it should display this in the
<prgn/postinst/ script and prompt the user to hit return to
acknowledge the message.  Copyright messages do not count as vitally
important (they belong in <tt>/usr/doc/copyright</>); neither do
instructions on how to use a program (these should be in on line
documentation, where all the users can see them).
<p>

Any necessary prompting should almost always be confined to the
post-installation script, and should be protected with a conditional
so that unnecssary prompting doesn't happen if a package's
installation fails and the <prgn/postinst/ is called with
<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
<p>

Errors which occur during the execution of an installation script
<em/must/ be checked and the installation <em/must not/ continue after
an error.
<p>

The section below on scripts in general applies to package maintainer
scripts too.

<sect>Scripts in general
<p>

All command scripts, including the package maintainer scripts inside
the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
the shell to be used to interpret them.
<p>

In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
<p>

Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
start with <tt>set -e</> so that errors are detected.  Every script
<em/must/ use <tt/set -e/ or check the exit status of <em/every/
command.
<p>

Perl scripts should check for errors when making any system calls,
including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
<tt/system/.
<p>

<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages.  See
Csh Programming Considered Harmful, one of the <tt/comp.unix.*/ FAQs.
If an upstream package comes with <prgn/csh/ scripts then you must make
sure that they start with <tt>#!/bin/csh</tt> and make your package
depend on <prgn/csh/.
<p>

<sect>Compilation options
<p>

Generally the following compilation parameters should be used:
<example>
CC = gcc
CFLAGS = -O2 -g -Wall # sane warning options vary between programs
LDFLAGS = # none
install -s # (or use strip on the files in debian/tmp)
</example>
<p>

Note that all installed binaries should be stripped, either by using
the <tt/-s/ flag to <prgn/install/, or by calling <prgn/strip/ on the
binaries after they have been copied into <tt>debian/tmp</> but
before the tree is made into a package.
<p>

Make sure that you do not link with <tt/-g/, as this makes a.out
compilers produce huge statically linked binaries.  The <tt/-g/ flag
is useful on compilation so that you have available a full set of
debugging symbols in your built source tree, in case anyone should
file a bug report involving (for example) a core dump.
<p>

The <tt/-N/ flag should not be used.  On a.out systems it may have
been useful for some very small binaries, but for ELF it has no good
effect.
<p>

It is up to the package maintainer to decide what compilation options
are best for the package.  Certain binaries (such as
computationally-intensive programs) may function better with certain
flags (<tt/-O3/, for example); feel free to use them.  Please use good
judgment here.  Don't use flags for the sake of it; only use them if
there is good reason to do so.  Feel free to override the upstream
author's ideas about which compilation options are best - they are
often inappropriate for our environment.
<p>

Please make sure that you use only released versions of shared
libraries to build your packages; otherwise other users will not be
able to run your binaries properly.  Producing source packages that
depend on unreleased compilers is also usually a bad idea.

<sect>Shared library packages
<p>

Packages involving shared libraries should be split up into several
binary packages.
<p>

For a straightforward library which has a development environment and
a runtime kit including just shared libraries you need to create two
packages: <tt/<var/libraryname/<var/soname//<footnote><var/soname/ is
the shared object name of the shared library - it's the thing that has
to match exactly between building an executable and running it for the
dynamic linker to be able run the program.  Usually the <var/soname/
is the major number of the library.</footnote> and
<tt/<var/libraryname/<var/soname/-dev/.
<p>

If you prefer only to support one development version time you may
name the development package <tt/<var/libraryname/-dev/; otherwise you
may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that the
user only installs one development version at a time (after all,
different development versions are likely to have the same header
files in them, causing a filename clash if both are installed).
Typically the development version will also need an exact version
dependency on the runtime library, to make sure that compilation and
linking happens correctly.
<p>

Packages which use the shared library should have a dependency on the
name of the shared library package,
<tt/<var/libraryname/<var/soname//.  When the <var/soname/ changes you
can have both versions of the library installed while moving from the
old library to the new.
<p>

If your package has some run-time support programs which use the
shared library you must <em/not/ put them in the shared library
package.  If you do that then you won't be able to install several
versions of the shared library without getting filename clashes.
Instead, either create a third package for the runtime binaries (this
package might typically be named <tt/<var/libraryname/-runtime/ - note
the absence of the <var/soname/ in the package name) or if the
development package is small include them in there.
<p>

If you have several shared libraries built from the same source tree
you can lump them all togther into a single shared library package,
provided that you change all their <var/soname/s at once (so that you
don't get filename clashes if you try to install different versions of
the combined shared libraries package).
<p>

Follow the directions in the <prgn/dpkg/ programmers' manual for
putting the shared library in its package, and make sure you include a
<tt/shlibs/ control area file with details of the dependencies for
packages which use the library.

<sect>Application configuration files, dotfiles and <tt>/etc/skel</>
<p>

Files in <tt>/etc/skel</> will automatically be copied into new user
accounts by <prgn/adduser/.  They should not be referenced there by
any program.
<p>

Therefore, if a program needs a dotfile to exist in advance in
<tt/$HOME/ to work sensibly that dotfile should be installed in
<tt>/etc/skel</> (and listed in conffiles, if it is not generated and
modified dynamically by the package's installation scripts).
<p>

However, programs that require dotfiles in order to operate sensibly
(dotfiles that they do not create themselves automatically, that is)
are a bad thing, and programs should be configured by the Debian
default installation as close to normal as possible.
<p>

Therefore, if a program in a Debian package needs to be configured in
some way in order to operate sensibly that configuration should be
done in a site-wide global configuration file elsewhere in
<tt>/etc</>.  Only if the program doesn't support a site-wide default
configuration and the package maintainer doesn't have time to add it
should a default per-user file be placed in <tt>/etc/skel</>.
<p>

<tt>/etc/skel</> should be as empty as we can make it.  This is
particularly true because there is no easy mechanism for ensuring that
the appropriate dotfiles are copied into the accounts of existing
users when a package is installed.
<p>

Ideally the sysadmin should ideally not have to do any configuration
other than that done (semi-)automatically by the postinst script.

<sect id="mail">Mail processing on Debian systems
<p>

Debian packages which process electronic mail, whether
mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
make sure that they are compatible with the configuration decisions
below.  Failure to do this may result in lost mail, broken <tt/From:/
lines, and other serious brain damage!
<p>

The mail spool is <tt>/var/spool/mail</> and the interface to send a
mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND).  The
mail spool is part of the base system and not part of the MTA package.
<p>

Mailboxes are locked using the <tt/<var/username/.lock/ lockfile
convention, rather than <prgn/fcntl/, <prgn/flock/ or <prgn/lockf/.
<p>

Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
chosen otherwise.  A MUA may remove a mailbox (unless it has
nonstandard permissions) in which case the MTA or another MUA must
recreate it if needed.  Mailboxes must be writeable by group mail.
<p>

The mail spool is 2775 <tt/mail.mail/, and MUA's need to be setgid
mail to do the locking mentioned above (and obviously need to avoid
accessing other users' mailboxes using this privilege).
<p>

<tt>/etc/aliases</> is the source file for the system mail aliases
(e.g.  postmaster, usenet, etc.) - it is the one which the sysadmin
and postinst scripts may edit.  After <tt>/etc/aliases</> is edited
the program or human editing it must call <prgn/newaliases/.  All MTA
packages should come with a <prgn/newaliases/ program, even if it does
nothing, but older MTA packages do not do this so programs should not
fail if <prgn/newaliases/ cannot be found.
<p>

The convention of writing <tt/forward to <var/address// in the mailbox
itself is not supported.  Use a <tt/.forward/ file instead.
<p>

The location for the <prgn/rmail/ program used by UUCP for incoming
mail is <tt>/usr/sbin/rmail</>, as per the FSSTND.  Likewise,
<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
<tt>/usr/sbin/rsmtp</> if it is supported.
<p>

If you need to know what name to use (for example) on outgoing news
and mail messages which are generated locally, you should use the file
<tt>/etc/mailname</>.  It will contain the portion after the username
and <tt/@/ (at) sign for email addresses of users on the machine
(followed by a newline).
<p>

A package should check for the existence of this file.  If it exists
it should use it without comment.<footnote>An MTA's prompting
configuration script may wish to prompt the user even if it finds this
file exists.</footnote> If it does not exist it should prompt the user
for the value and store it in <tt>/etc/mailname</> as well as using it
in the package's configuration.  The prompt should make it clear that
the name will not just be used by that package.  E.g., in this
situation the INN package says:
<example>
Please enter the `mail name' of your system.  This is the hostname
portion of the address to be shown on outgoing news and mail messages.
The default is <var/syshostname/, your system's host name.
Mail name [`<var/syshostname/']:
</example>
where <var/syshostname/ is the output of <tt/hostname -fqdn/.


<sect>Packages which can use the X shared libraries
<p>

Some programs can be configured with or without support for X Windows.
Typically these binaries produced when configured for X will need the
X shared libraries to run.
<p>

Such programs should be configured <em/with/ X support, and should
declare a dependency on <tt/elf-x11r6lib/ (for the X11R6 libraries).
Users who wish to use the program can install just the relatively
small <tt/xlib/ package, and do not need to install the whole of X.
<p>

Do not create two versions (one with X support and one without) of
your package.


<sect>Games
<p>

The permissions on /var/lib/games are 755 <tt/root.root/.
<p>

Each game decides on its own security policy.
<p>

Games which require protected, privileged access to high-score files,
savegames, &amp;c, must be made set-<em/group/-id (mode 2755) and
owned by <tt/root.games/, and use files and directories with
appropriate permissions (770 <tt/root.games/, for example).  They must
<em/not/ be made set-<em/user/-id, as this causes security
problems.<footnote>If an attacker can subvert any set-user-id game
they can overwrite the executable of any other, causing other players
of these cames to run a trojan.  With a set-group-id game the attacker
only gets access to less important game data, and if they can get at
the other players' accounts at all it will take considerably more
effort.</footnote>
<p>

Some packages, for example some fortune cookie programs, are
configured by the upstream authors to install with their data files or
other static information made unreadable so that they can only be
accessed through set-id programs provided.  Do not do this in a Debian
package: anyone can download the <tt/.deb/ file and read the data from
it, so there is no point making the files unreadable.  Not making the
files unreadable also means that you don't have to make so many
programs set-id, which reduces the risk of a security hole.

<sect>Allocating package-specific users and groups
<p>

If you need to create a new user or group for your package there are
two possibilities.  Firstly, you may need to make some files in the
binary package be owned by this user or group, or you may need to
compile the user or group id (rather than just the name) into the
binary (though this latter should be avoided if possible).  In this
case you need a statically allocated id.
<p>

You must ask for a user or group id from the base system maintainer,
and must not release the package until you have been allocated one.
Once you have been allocated one you must make the package depend
on a version of the base system with the id present in
<tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or alternatively arrange
for your package to create the user or group itself with the correct
id (using <tt/adduser/) in its pre- or post-installation script (the
latter is to be preferred if it is possible).
<p>

On the other hand, the program may able to determine the uid or gid
from the group name at runtime, so that a dynamic id can be used.  In
this case you must choose an appropriate user or group name,
discussing this on <prgn/debian-devel/ and checking with the base system
maintainer that it is unique and that they do not wish you to use a
statically allocated id instead.  When this has been checked you must
arrange for your package to create the user or group if necessary
using <prgn/adduser/ in the pre- or post-installation script (again, the
latter is to be preferred if it is possible).
<p>

Note that changing the numeric value of an id associated with a name
is very difficult, and involves searching the filesystem for all
appropriate files.  You need to think carefully whether a static or
dynamic id is required, since changing your mind later will cause
problems.

<chapt id="sourcepkg">Source package

<sect>Releases of packages by other than the usual Debian maintainer
<p>

Under certain circumstances it is necessary for someone other than the
usual package maintainer to make a release of a package.  For example,
a porter for another architecture may have to make some small changes
to the source package and does not wish to wait with uploading their
release until the main maintainer has incorporated the patch, or a
serious security problem may have come to light requiring immediate
attention.
<p>

Maintainers other than the usual package maintainer should make as few
changes to the package as possible, and they should always send a
unified context diff (<tt/diff -u/) detailing their changes to the bug
tracking system properly flagged with the correct package so that the
usual maintainer is kept aware of the situation.
<p>

When someone other than the usual maintainer releases a package they
should add a new component to the <var/debian-revision/ component of
the version number - that is, the portion after the (last) hyphen.
This extra component will start at <tt/1/.  This is to avoid
`stealing' one of the usual maintainer's version numbers, possibly
disrupting their work.  If there is no <var/debian-revision/ component
in the version number then one should be created, starting at <tt/1/.
<p>

If it is absolutely necessary for someone other than the usual
maintainer to make a release based on a new upstream version then the
person making the release should start with the <var/debian-revision/
value <tt/0.1/.  The usual maintainer of a package should start their
<var/debian-revision/ numbering at <tt/1/.


<sect>Standards conformance and <tt/Standards-Version/
<p>

You should specify the most recent version of the packaging standards
with which your package complies in the source package's
<tt/Standards-Version/ field.
<p>

This value will be used to file bug reports automatically if your
package becomes too much out of date.
<p>

The value corresponds to a version of the Debian manuals, as can be
found on the title page or page headers and footers (depending on the
format).  The value for this version of the manuals and packaging
standards is <tt/&manuals-version;/.
<p>

The version number has four components - major and minor number and
major and minor patchlevel.  When the standards change in a way that
requires every package to change the major number will be changed.
Significant changes that will require work in many packages will be
signaled by a change to the minor number.  The major patchlevel will
be changed for any change to the meaning of the standards, however
small; the minor patchlevel will be changed when only cosmetic,
typographical or other edits which do not change the meaning are made,
or changes which do not affect the contents of packages.
<p>

You should regularly, and especially if your package has become out of
date, install the most recent version of dpkg and read
<tt>/usr/doc/dpkg/changelog-manuals</> to see which changes, if any,
are relevant.  If any are relevant you should look up the relevant
section in the policy or programmers' manuals and update your package.
When your package complies with the new standards you may update the
<tt/Standards-Version/ source package field and release it.


<sect>Documentation and the <tt/changelog/
<p>

Document your changes and updates to the source package properly in
the <tt>debian/changelog</tt> file.
<p>

A copy of the file which will be installed in
<tt>/usr/doc/<var/package//copyright</tt> should be in
<tt>debian/copyright</tt>.
<p>

In non-experimental packages you may only use a format for
<tt>debian/changelog</> which is supported by the most recent released
version of <prgn/dpkg/.  If your format is not supported and there is
general support for it you should contact the <prgn/dpkg/ maintainer
to have the parser script for your format included in the <prgn/dpkg/
package.<footnote>You will need to agree that the parser and its
manpage may be distributed under the GNU GPL, just as the rest of
<prgn/dpkg/ is.</footnote>

<sect>Changes to the upstream sources
<p>

If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
scripts are used, you should edit the <tt/.in/ files rather than
editing the <prgn/Makefile/ directly.  This allows the user to
reconfigure the package if necessary.  You should <em/not/ configure
the package and edit the generated <prgn/Makefile/!  This makes it
impossible for someone else to later reconfigure the package.
<p>

If changes to the source code are made that are generally applicable
please try to get them included in the upstream version of the package
by supplying the upstream authors with the changes in whatever form
they prefer.
<p>

If you need to configure the package differently for Debian or for
Linux, and the upstream source doesn't provide a way to configure it
the way you need to, please add such configuration facilities (for
example, a new <prgn/autoconf/ test or <tt/#define/) and send the
patch to the upstream authors, with the default set to the way they
originally had it.  You can then easily override the default in your
<tt>debian/rules</tt> or wherever is appropriate.

<sect>Error trapping in makefiles
<p>

When <prgn/make/ invokes a command in a makefile (including your
package's upstream makefiles and the <tt>debian/rules</>) it does so
using <tt/sh/.  This means that <tt/sh/'s usual bad error handling
properties apply: if you include a miniature script as one of the
commands in your makefile you'll find that if you don't do anything
about it then errors are not detected and <prgn/make/ will blithely
continue after problems.
<p>

Every time you put more than one shell command (this includes using a
loop) in a makefile command you <em/must/ make sure that errors are
trapped.  For simple compound commands, such as changing directory and
then running a program, using <tt/&amp;&amp;/ rather than semicolon as
a command separator is sufficient.  For more complex commands
including most loops and conditionals you must include a separate
<tt/set -e/ command at the start of every makefile command that's
actually one of these miniature shellscripts.

<chapt id="developer">Procedure - how to participate in the Debian project

<sect>Before you start work on a package
<p>

So, you've read all the documentation, you understand what everything
in the <prgn/hello/ example package is for, and you're about to
Debianise your favourite package.  How do you actually become a Debian
developer so that your work can be incorporated into the Project?
<p>

Firstly, subscribe to <prgn/debian-devel/ if you haven't already.
Send the word <tt/subscribe/ in the <em/Subject/ of a mail to
<email/debian-devel-REQUEST@lists.debian.org/.  In case of problems
contact the list administrator, Anders Chrigstrom <email/ac@netg.se/.
<p>

You should to subscribe and lurk for a bit before doing any coding,
and you should post about your intentions to work on something to
avoid duplicated effort.
<p>

If you do not have a PGP key yet generate one.  You should probably
read the PGP manual, as it has much important information which is
critical to its security.  Many more security failures are due to
human error than to software failure or high-powered spy techniques.
<p>

If you live in a country where use of cryptography even for signing is
forbidden then please contact us so we can make special arrangements.
This does not apply in France, where I believe only encryption and not
signing is forbidden.

<sect>When you have a package to upload
<p>

When you have your package ready to be uploaded you must send a
message to the project leader, Bruce Perens <email/bruce@pixar.com/,
the administrator of <tt/master.debian.org/, Simon Shapiro
<email/shimon@i-connect.net/, the mailing list administrator, Anders
Chrigstrom <email/ac@netg.se/ and the <prgn/dpkg/ maintainer, Ian
Jackson <email/ijackson@gnu.ai.mit.edu/.
<p>

The message should say what you've done and who you are, and should
ask for an account on <prgn/master/ and to be subscribed to
<prgn/debian-private/ (the developers-only mailing list).  It should
contain your PGP key (extracted using <tt/pgp -kxa/) for the database
of keys which is shipped with <prgn/dpkg/.

When you have your personal account on <prgn/master/ log in and
transfer the files to
<tt>/home/Debian/ftp/private/project/Incoming</>.  You cannot upload
to <prgn/Incoming/ on <prgn/master/ using anonymous FTP.
<p>

You can also upload files to <prgn/Incoming/ via a <prgn/cron/-driven
upload queue in Europe on <ftpsite/chiark.chu.cam.ac.uk/.  For details
connect to <prgn/chiark/ using anonymous FTP and read
<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.

<sect id="changesfiles">Upload handling - <tt/.changes/ files
<p>

When a package is uploaded to the Debian FTP archive, it must be
accompanied by a <tt/.changes/ file which gives directions for its
handling.  This is usually generated by <prgn/dpkg-genchanges/.
<p>

This file is a control file with the following fields:
<list compact>
<item><tt/Format/
<item><tt/Date/
<item><tt/Source/
<item><tt/Binary/
<item><tt/Architecture/
<item><tt/Version/
<item><tt/Distribution/
<item><tt/Urgency/
<item><tt/Maintainer/
<item><tt/Description/
<item><tt/Changes/
<item><tt/Files/
</list>
<p>

All of them are mandatory for a Debian upload.  See the list of
control fields in the <prgn/dpkg/ programmers' manual for the contents
of these fields.
<p>

The first time a version is uploaded which corresponds to a particular
upstream version the original source tarfile should be uploaded and
included in the <tt/.changes/ file; subsequent times the very same
tarfile should be used to build the new diffs and <tt/.dsc/ files, and
it need not then be uploaded.
<p>

By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will
include the original source tarfile if and only if the Debian revision
part of the source version number is <tt/0/ or <tt/1/, indicating a
new upstream version.  This behaviour may be modified by using
<tt/-sa/ to always include it or <tt/-sd/ to always leave it out.
<p>

If no original source is included in the upload then the original
source tarfile used by <prgn/dpkg-source/ when constructing the
<tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte
identical with the one already in the archive.  If there is some
reason why this is not the case then the new version of the original
source should be uploaded, possibly by using the <tt/-sa/ flag.

<sect id="mailinglists">The Debian mailing lists
<p>

The mailing list server is at <tt/lists.debian.org/.  Mail
<tt/debian-<var/foo/-REQUEST@lists.debian.org/<footnote>where
<tt/debian-<var/foo// is the name of the list</footnote> with the word
<tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to
unsubscribe.
<p>

When replying to messages on the mailing list, please do not send a
carbon copy (<tt/CC/ - this does not mean `courtesy copy') to the
original poster.  Anyone who posts to a mailing list should read it to
see the responses.
<p>

As ever on the net, please trim down the quoting of articles you're
replying to.  In general, please adhere to the usual conventions for
posting messages.


<chapt id="conversion">Conversion procedure from old source packages
<p>

This is a brief summary of the procedure for converting a
pre-2.0.0.0-format source package into the new format.
<p>

You are strongly advised to download and examine the <prgn/hello/
package, and to read the section in the <prgn/dpkg/ programmers'
manual describing the source packaging tools.  More detail about the
exact functionality of these tools is available in <manref
name=dpkg-source section=1>.
<p>

<list>

<item>
Download the original source code from wherever it can be found and do
any rearrangement required to make it look like the original tree of
the Debian source.  Put it in
<tt><var/package/-<var/upstream-version/.orig/</> or
<tt/<var/package/_<var/upstream-version/.orig.tar.gz/.

<item>
Rename all files <tt/debian.*/ to <tt>debian/*</>.  There may be some
exceptions to this, but this is a good start.

<item>
Edit the <tt>debian/changelog</> - create or rename it if necessary.
Add a new revision to the top with the appropriate details, and a
local variables entry to the bottom to set Emacs to the right mode:
<example>
Local variables:
mode: debian-changelog
End:
</example>

<item>
Edit/create <tt>debian/control</>:
<list compact>
<item>
Remove the <tt/Version/ field.  If it is generated unusually (not
equal to the source version) you must use the -v option to
dpkg-gencontrol (see below).  <tt/Section/, <tt/Priority/,
<tt/Maintainer/ go above the first blank line, most of the rest below.

<item>
Reorder the fields and add a blank line at an appropriate point,
separating the source package fields from the binary package
fields.

<item>
Add the <tt/Source/ field.

<item>
Add the <tt/Standards-Version/ field.  The current value is
<tt/&manuals-version;/.

<item>
Change the <tt/Architecture/ field for each package to <tt/any/,
<tt/all/ or whatever.  If there isn't an <tt/Architecture/ field add
one.

<item>
If any other seddery or things used to happen to make the binary
control files use <prgn/dpkg-gencontrol/'s variable substitution
features to achieve the same effect.  Use <tt>debian/substvars</> if
you need to put unusally-generated information (apart from details of
<tt/.deb/ files) in the <tt/.changes/ file too.
</list>

<item>
Edit the <tt>debian/rules</>:
<list compact>
<item>
Remove the <prgn/source/ and <prgn/diff/ and any <prgn/changes/ and
<prgn/dist/ targets.  These things now happen in a package-independent
way and are not done by <tt>debian/rules</>.
<item>
Split the <prgn/binary/ target into <prgn/binary-arch/ and
<prgn/binary-indep/; in many cases all of <prgn/binary/ should go into
<prgn/binary-arch/.  Create the <prgn/binary/ target and the unused of
the two other <prgn/binary-*/ targets if there is one - you can copy
the ones from the <prgn/hello/ package.
<item>
Change the <prgn/binary/ target to use <prgn/dpkg-gencontrol/ to make
the package control file(s).  Move it to after all the files have been
installed but just before the last <prgn/chown/ and <prgn/chmod/ in
the target.
<item>
Change occurrences of <tt/debian-tmp/ to <tt>debian/tmp</>.
<item>
Change occurrences of <tt/debian.{post,pre}{inst,rm}/ to
<tt>debian/*</>.
<item>
Remove the version number setting at the top, if there is one.
<item>
Ensure that the package's Debian-specific and upstream changelogs are
installed.
</list>

<item>
Check that the <tt>debian/README</> is really the copyright file, and
if so rename it to <tt>debian/copyright</> and edit
<tt>debian/rules</> to cope with this and to change the installation
of the copyright file from <tt>/usr/doc/<var/package//copyright</>
instead of <tt>/usr/doc/copyright/<var/package/</>.  If it isn't then
find <tt>debian/copyright</> and decide what to do with the
<tt>README</>.

<item>
Check for various other anachronisms and problems:
<list compact>
<item>
Remove any <tt/Package_Revision/, <tt/Package-Revision/ or
<tt/Revision/ fields.
<item>
Rename <tt/Optional/ to <tt/Suggests/, <tt/Recommended/ to
<tt/Recommends/.
<item>
Change <tt>/usr/doc/examples/<var/package/</> to
<tt>/usr/doc/<var/package//examples</>.
<item>
Make sure that manpages are installed compressed.
<item>
Check that the description has an extended description, is
well-formatted and meaningful and helpful to people wanting to know
whether to install a package.
</list>

<item>
Look everything over.

<item>
Do a test build using <tt/dpkg-buildpackage -ur -uc -sa
-r<var/whatever//.  Check the permissions and locations of files in
the resulting package by eyeballing the output of <tt/dpkg-deb
--contents/, and check that the source build happened OK.  Test
install the binary package(s) and test extract the source package(s).

<item>
Sign the release: either rebuild everything with <tt/dpkg-buildpackage
-sa/, or PGP-sign the <tt/.dsc/, rebuild the <tt/.changes/ using
<tt/dpkg-genchanges -sa/, and then PGP-sign the <tt/.changes/.

</list>
<p>

The use of <tt/-sa/ on <prgn/dpkg-buildpackage/ and
<prgn/dpkg-genchanges/ is important when doing the first
build/uploading of a new-format source package.  Unless this happens
to be Debian revision <tt/0/ or <tt/1/ by default the original source
tarfile will not be included in the uploaded files listed in the
<tt/.changes/ file, and so it won't be installed on the FTP site.
<tt/-sa/ requests that the original source be included regardless.

</book>