is used by, a significant number of packages, and
therefore should not be changed without peer
review. Package maintainers can then rely on this
- interfaces not changing, and the package
- management software authors need to ensure
- compatibility with these interface
- definitions. (Control file and changelog file
- formats are examples.)
+ interface not changing, and the package management
+ software authors need to ensure compatibility with
+ this interface definition. (Control file and
+ changelog file formats are examples.)
</item>
<tag>Chosen Convention</tag>
<item>
The Debian Free Software Guidelines (DFSG) form our
definition of "free software". These are:
<taglist>
- <tag>Free Redistribution
+ <tag>1. Free Redistribution
</tag>
<item>
The license of a Debian component may not restrict any
sources. The license may not require a royalty or
other fee for such sale.
</item>
- <tag>Source Code
+ <tag>2. Source Code
</tag>
<item>
The program must include source code, and must allow
distribution in source code as well as compiled form.
</item>
- <tag>Derived Works
+ <tag>3. Derived Works
</tag>
<item>
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
</item>
- <tag>Integrity of The Author's Source Code
+ <tag>4. Integrity of The Author's Source Code
</tag>
<item>
The license may restrict source-code from being
Project encourages all authors to not restrict any
files, source or binary, from being modified.)
</item>
- <tag>No Discrimination Against Persons or Groups
+ <tag>5. No Discrimination Against Persons or Groups
</tag>
<item>
The license must not discriminate against any person
or group of persons.
</item>
- <tag>No Discrimination Against Fields of Endeavor
+ <tag>6. No Discrimination Against Fields of Endeavor
</tag>
<item>
The license must not restrict anyone from making use
used in a business, or from being used for genetic
research.
</item>
- <tag>Distribution of License
+ <tag>7. Distribution of License
</tag>
<item>
The rights attached to the program must apply to all
for execution of an additional license by those
parties.
</item>
- <tag>License Must Not Be Specific to Debian
+ <tag>8. License Must Not Be Specific to Debian
</tag>
<item>
The rights attached to the program must not depend on
rights as those that are granted in conjunction with
the Debian system.
</item>
- <tag>License Must Not Contaminate Other Software
+ <tag>9. License Must Not Contaminate Other Software
</tag>
<item>
The license must not place restrictions on other
that all other programs distributed on the same medium
must be free software.
</item>
- <tag>Example Licenses
+ <tag>10. Example Licenses
</tag>
<item>
The "GPL," "BSD," and "Artistic" licenses are examples of
<heading>Copyright considerations</heading>
<p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
+ Every package must be accompanied by a verbatim copy of its
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>
(see <ref id="copyrightfile"> for further details).
</p>
<em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
<em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
<em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
- <em>zope</em>.
+ <em>zope</em>. The additional section <em>debian-installer</em>
+ contains special packages used by the installer and is not used
+ for normal Debian packages.
+ </p>
+
+ <p>
+ For more information about the sections and their definitions,
+ see the <url id="http://packages.debian.org/unstable/"
+ name="list of sections in unstable">.
</p>
</sect>
<sect id="dpkgcopyright">
<heading>Copyright: <file>debian/copyright</file></heading>
<p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
+ Every package must be accompanied by a verbatim copy of its
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>
(see <ref id="copyrightfile"> for further details). Also see
- <ref id="pkgcopyright"> for further considerations relayed
+ <ref id="pkgcopyright"> for further considerations related
to copyrights for packages.
</p>
</sect>
<p>
It must start with the line <tt>#!/usr/bin/make -f</tt>,
so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
+ invoking <prgn>make</prgn> explicitly. That is, invoking
+ either of <tt>make -f debian/rules <em>args...</em></tt>
+ or <tt>./debian/rules <em>args...</em></tt> must result in
+ identical behavior.
</p>
<p>
Since an interactive <file>debian/rules</file> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all <em>required targets</em> MUST be
+ package, all <em>required targets</em> must be
non-interactive. At a minimum, required targets are the
ones called by <prgn>dpkg-buildpackage</prgn>, namely,
<em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
<p>
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
+ Field values are case-sensitive unless the description of the
+ field says otherwise.
</p>
<p>
<heading><tt>Priority</tt></heading>
<p>
- This field represents how important that it is that the user
+ This field represents how important it is that the user
have the package installed. See <ref id="priorities">.
</p>
</p>
<p>
- See <ref id="debianrules"> for information how to get the
- architecture for the build process.
+ See <ref id="debianrules"> for information on how to get
+ the architecture for the build process.
</p>
</sect1>
<p>
Thus only the first three components of the policy version
are significant in the <em>Standards-Version</em> control
- field, and so either these three components or the all
- four components may be specified.<footnote>
+ field, and so either these three components or all four
+ components may be specified.<footnote>
In the past, people specified the full version number
in the Standards-Version field, for example "2.3.0.0".
Since minor patch-level changes don't introduce new
<p>
In a <file>.changes</file> file, the <tt>Description</tt>
field contains a summary of the descriptions for the packages
- being uploaded. For this caes, the first line of the field
+ being uploaded. For this case, the first line of the field
value (the part on the same line as <tt>Description:</tt>) is
always empty. The content of the field is expressed as
continuation lines, one line per package. Each line is
for the most recent version should be returned first, and
entries should be separated by the representation of a
blank line (the "title" line may also be followed by the
- representation of blank line).
+ representation of a blank line).
</p>
</sect1>
no new original source archive is being distributed the
<tt>.dsc</tt> must still contain the <tt>Files</tt> field
entry for the original source archive
- <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
but the <file>.changes</file> file should leave it out. In
this case the original source archive on the distribution
site must match exactly, byte-for-byte, the original
<heading>Controlling terminal for maintainer scripts</heading>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- Because these scripts may be executed with standard output
- redirected into a pipe for logging purposes, Perl scripts
- should set unbuffered output by setting <tt>$|=1</tt> so
- that the output is printed immediately rather than being
- buffered.
+ Maintainer scripts are not guaranteed to run with a controlling
+ terminal and may not be able to interact with the user. They
+ must be able to fall back to noninteractive behavior if no
+ controlling terminal is available. Maintainer scripts that
+ prompt via a program conforming to the Debian Configuration
+ Management Specification (see <ref id="maintscriptprompt">) may
+ assume that program will handle falling back to noninteractive
+ behavior.
</p>
</sect>
+
<sect id="exitstatus">
<heading>Exit status</heading>
</example>
If this works, then the old-version is
"Installed", if not, the old version is in a
- "Failed-Config" state.
+ "Half-Configured" state.
</item>
</enumlist>
</item>
If this fails, the package is left in a
"Half-Installed" state, which requires a
reinstall. If it works, the packages is left in
- a "Config Files" state.
+ a "Config-Files" state.
</item>
<item>
Otherwise (i.e., the package was completely purged):
<var>new-postrm</var> abort-install
</example>
If the error-unwind fails, the package is in a
- "Half Installed" phase, and requires a
+ "Half-Installed" phase, and requires a
reinstall. If the error unwind works, the
package is in a not installed state.
</item>
<example compact="compact">
<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
<example compact="compact">
<var>new-postrm</var> abort-upgrade <var>old-version</var>
</example>
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
<example compact="compact">
<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
<p>
- If this fails, the package is in a "Failed-Config"
+ If this fails, the package is in a "Half-Configured"
state, or else it remains "Installed".
</p>
</item>
be <em>unpacked</em> the pre-dependency can be
satisfied if the depended-on package is either fully
configured, <em>or even if</em> the depended-on
- package(s) are only unpacked or half-configured,
- provided that they have been configured correctly at
- some point in the past (and not removed or partially
- removed since). In this case, both the
+ package(s) are only unpacked or in the "Half-Configured"
+ state, provided that they have been configured
+ correctly at some point in the past (and not removed
+ or partially removed since). In this case, both the
previously-configured and currently unpacked or
- half-configured versions must satisfy any version
+ "Half-Configured" versions must satisfy any version
clause in the <tt>Pre-Depends</tt> field.
</p>
<p>
A package will not be regarded as causing breakage merely
because its configuration files are still installed; it must
- be at least half-installed.
+ be at least "Half-Installed".
</p>
<p>
<p>
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
- half-installed.
+ "Half-Installed".
</p>
<p>
</p>
<p>
- If you are creating a udeb for use in the Debian Installer, you
- will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
- the dependency line of type <tt>udeb</tt> by adding
- <tt>-tudeb</tt> as option<footnote>
+ If you are creating a udeb for use in the Debian Installer,
+ you will need to specify that <prgn>dpkg-shlibdeps</prgn>
+ should use the dependency line of type <tt>udeb</tt> by
+ adding the <tt>-tudeb</tt> option<footnote>
<prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
will automatically add this option if it knows it is
processing a udeb.
for 64 bit binaries is removed.
</p>
</item>
+ <item>
+ <p>
+ The requirement for object files, internal binaries, and
+ libraries, including <file>libc.so.*</file>, to be located
+ directly under <file>/lib{,32}</file> and
+ <file>/usr/lib{,32}</file> is amended, permitting files
+ to instead be installed to
+ <file>/lib/<var>triplet</var></file> and
+ <file>/usr/lib/<var>triplet</var></file>, where
+ <tt><var>triplet</var></tt> is the value returned by
+ <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
+ architecture of the package. Packages may <em>not</em>
+ install files to any <var>triplet</var> path other
+ than the one matching the architecture of that package;
+ for instance, an <tt>Architecture: amd64</tt> package
+ containing 32-bit x86 libraries may not install these
+ libraries to <file>/usr/lib/i486-linux-gnu</file>.
+ <footnote>
+ This is necessary in order to reserve the directories for
+ use in cross-installation of library packages from other
+ architectures, as part of the planned deployment of
+ <tt>multiarch</tt>.
+ </footnote>
+ </p>
+ <p>
+ Applications may also use a single subdirectory under
+ <file>/usr/lib/<var>triplet</var></file>.
+ </p>
+ <p>
+ The execution time linker/loader, ld*, must still be made
+ available in the existing location under /lib or /lib64
+ since this is part of the ELF ABI for the architecture.
+ </p>
+ </item>
<item>
<p>
The requirement that
symlinked there, is relaxed to a recommendation.
</p>
</item>
+ <item>
+ <p>
+ The following directories in the root filesystem are
+ additionally allowed: <file>/sys</file> and
+ <file>/selinux</file>. <footnote>These directories
+ are used as mount points to mount virtual filesystems
+ to get access to kernel information.</footnote>
+ </p>
+ </item>
</enumlist>
</p>
</p>
<p>
- Note, that this applies only to directories <em>below</em>
- <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- Packages must not create sub-directories in the directory
- <file>/usr/local</file> itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
+ Note that this applies only to
+ directories <em>below</em> <file>/usr/local</file>,
+ not <em>in</em> <file>/usr/local</file>. Packages must
+ not create sub-directories in the
+ directory <file>/usr/local</file> itself, except those
+ listed in FHS, section 4.5. However, you may create
+ directories below them as you wish. You must not remove
+ any of the directories listed in 4.5, even if you created
+ them.
</p>
<p>
<sect1>
<heading>The system-wide mail directory</heading>
<p>
- The system-wide mail directory is <file>/var/mail</file>. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
+ The system-wide mail directory
+ is <file>/var/mail</file>. This directory is part of the
+ base system and should not be owned by any particular mail
+ agents. The use of the old
location <file>/var/spool/mail</file> is deprecated, even
though the spool may still be physically located there.
</p>
</p>
</item>
- <tag>1000-29999:</tag>
+ <tag>1000-59999:</tag>
<item>
<p>
Dynamically allocated user accounts. By default
</p>
</item>
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
<tag>60000-64999:</tag>
<item>
<p>
</p>
</sect1>
- <sect1>
+ <sect1 id="writing-init">
<heading>Writing the scripts</heading>
<p>
option.
</p>
+ <p>
+ Be careful of using <tt>set -e</tt> in <file>init.d</file>
+ scripts. Writing correct <file>init.d</file> scripts requires
+ accepting various error exit statuses when daemons are already
+ running or already stopped without aborting
+ the <file>init.d</file> script, and common <file>init.d</file>
+ function libraries are not safe to call with <tt>set -e</tt>
+ in effect<footnote>
+ <tt>/lib/lsb/init-functions</tt>, which assists in writing
+ LSB-compliant init scripts, may fail if <tt>set -e</tt> is
+ in effect and echoing status messages to the console fails,
+ for example.
+ </footnote>. For <tt>init.d</tt> scripts, it's often easier
+ to not use <tt>set -e</tt> and instead check the result of
+ each command separately.
+ </p>
+
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
<prgn>anacron</prgn>. Thus, you should only use this
directory for jobs which may be skipped if the system is not
running.)</p>
+ <p>
+ Unlike <file>crontab</file> files described in the IEEE Std
+ 1003.1-2008 (POSIX.1) available from
+ <url id="http://www.opengroup.org/onlinepubs/9699919799/"
+ name="The Open Group">, the files in
+ <file>/etc/cron.d</file> and the file
+ <file>/etc/crontab</file> have seven fields; namely:
+ <enumlist>
+ <item>Minute [0,59]</item>
+ <item>Hour [0,23]</item>
+ <item>Day of the month [1,31]</item>
+ <item>Month of the year [1,12]</item>
+ <item>Day of the week ([0,6] with 0=Sunday)</item>
+ <item>Username</item>
+ <item>Command to be run</item>
+ </enumlist>
+ Ranges of numbers are allowed. Ranges are two numbers
+ separated with a hyphen. The specified range is inclusive.
+ Lists are allowed. A list is a set of numbers (or ranges)
+ separated by commas. Step values can be used in conjunction
+ with ranges.
+ </p>
<p>
- The scripts or crontab entries in these directories should
+ The scripts or <tt>crontab</tt> entries in these directories should
check if all necessary programs are installed before they
try to execute them. Otherwise, problems will arise when a
package was removed but not purged since configuration files
- are kept on the system in this situation.</p>
+ are kept on the system in this situation.
+ </p>
+
+ <p>
+ Any <tt>cron</tt> daemon must provide
+ <file>/usr/bin/crontab</file> and support normal
+ <tt>crontab</tt> entries as specified in POSIX. The daemon
+ must also support names for days and months, ranges, and
+ step values. It has to support <file>/etc/crontab</file>,
+ and correctly execute the scripts in
+ <file>/etc/cron.d</file>. The daemon must also correctly
+ execute scripts in
+ <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
+ </p>
</sect>
<sect id="menus">
language currently used to implement it.
</p>
<p>
- Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
- should almost certainly start with <tt>set -e</tt> so that
- errors are detected. Every script should use
- <tt>set -e</tt> or check the exit status of <em>every</em>
- command.
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
+ <file>init.d</file> scripts should almost certainly start
+ with <tt>set -e</tt> so that errors are detected.
+ <file>init.d</file> scripts are something of a special case, due
+ to how frequently they need to call commands that are allowed to
+ fail, and it may instead be easier to check the exit status of
+ commands directly. See <ref id="writing-init"> for more
+ information about writing <file>init.d</file> scripts.
+ </p>
+ <p>
+ Every script should use <tt>set -e</tt> or check the exit status
+ of <em>every</em> command.
</p>
-
<p>
Scripts may assume that <file>/bin/sh</file> implements the
SUSv3 Shell Command Language<footnote>
<heading>Device files</heading>
<p>
- Packages must not include device files in the package file
- tree.
+ Packages must not include device files or named pipes in the
+ package file tree.
</p>
<p>
<file>/dev/cu*</file> devices should be changed to use
<file>/dev/ttyS*</file>.
</p>
+
+ <p>
+ Named pipes needed by the package must be created in
+ the <prgn>postinst</prgn> script<footnote>
+ It's better to use <prgn>mkfifo</prgn> rather
+ than <prgn>mknod</prgn> to create named pipes so that
+ automated checks for packages incorrectly creating device
+ files with <prgn>mknod</prgn> won't have false positives.
+ </footnote> and removed in
+ the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
+ appropriate.
+ </p>
</sect>
<sect id="config-files">
security policy by changing the permissions on a binary:
they can do this by using <prgn>dpkg-statoverride</prgn>, as
described below.<footnote>
- Ordinary files installed by <prgn>dpkg</prgn> (as
- opposed to <tt>conffile</tt>s and other similar objects)
- normally have their permissions reset to the distributed
- permissions when the package is reinstalled. However,
- the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behavior. If you use this method, you should
- remember to describe <prgn>dpkg-statoverride</prgn> in
- the package documentation; being a relatively new
- addition to Debian, it is probably not yet well-known.
+ Ordinary files installed by <prgn>dpkg</prgn> (as
+ opposed to <tt>conffile</tt>s and other similar objects)
+ normally have their permissions reset to the distributed
+ permissions when the package is reinstalled. However,
+ the use of <prgn>dpkg-statoverride</prgn> overrides this
+ default behavior.
</footnote>
Another method you should consider is to create a group for
people allowed to use the program(s) and make any setuid
use <file>/usr/bin/sensible-editor</file> and
<file>/usr/bin/sensible-pager</file> as the editor or pager
program respectively. These are two scripts provided in the
- Debian base system that check the EDITOR and PAGER variables
- and launch the appropriate program, and fall back to
- <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
- variable is not set.
+ <package>sensible-utils</package> package that check the EDITOR
+ and PAGER variables and launch the appropriate program, and fall
+ back to <file>/usr/bin/editor</file>
+ and <file>/usr/bin/pager</file> if the variable is not set.
</p>
<p>
<p>
Customization of programs' X resources may also be
supported with the provision of a file with the same name
- as that of the package placed in the
- <file>/etc/X11/Xresources/</file> directory, which must
- registered as a <tt>conffile</tt> or handled as a
+ as that of the package placed in
+ the <file>/etc/X11/Xresources/</file> directory, which
+ must be registered as a <tt>conffile</tt> or handled as a
configuration file.<footnote>
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
It was previously necessary for packages installing info
documents to run <prgn>install-info</prgn> from maintainer
scripts. This is no longer necessary. The installation
- system now uses dpkg hooks.
+ system now uses dpkg triggers.
</footnote>
- This file must not be included in packages.
+ This file must not be included in packages. Packages containing
+ info documents should depend on <tt>dpkg (>= 1.15.4) |
+ install-info</tt> to ensure that the directory file is properly
+ rebuilt during partial upgrades from Debian 5.0 (lenny) and
+ earlier.
</p>
<p>
* example: (example). An example info directory entry.
@end direntry
</example>
+ to the Texinfo source of the document and ensure that the info
+ documents are rebuilt from source during the package build.
</footnote>
- to the Texinfo source of the document and ensure that the info
- documents are rebuilt from source during the package build.
</p>
</sect>
<p>
Please note that this does not override the section on
changelog files below, so the file
- <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+ <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
must refer to the changelog for the current version of
<var>package</var> in question. In practice, this means
that the sources of the target and the destination of the
<p>
Every package must be accompanied by a verbatim copy of its
- copyright and distribution license in the file
+ copyright information and distribution license in the file
<file>/usr/share/doc/<var>package</var>/copyright</file>. This
file must neither be compressed nor be a symbolic link.
</p>
</p>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- See <ref id="controllingterminal">.
+ The maintainer scripts are not guaranteed to run with a
+ controlling terminal and may not be able to interact with
+ the user. See <ref id="controllingterminal">.
</p>
</item>
</p>
</sect1>
-
- <sect1 id="pkg-dpkgchangelog">
- <heading><file>debian/changelog</file></heading>
-
- <p>
- See <ref id="dpkgchangelog">.
- </p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
-
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
-
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
- or
- <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
-
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
-
- <p>
- The fields are:
- <list compact="compact">
- <item><qref id="f-Source"><tt>Source</tt></qref></item>
- <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
- <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
- <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Date"><tt>Date</tt></qref></item>
- <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
- </list>
- </p>
-
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
-
- <p>
- For the format of the <tt>Changes</tt> field see
- <ref id="f-Changes">.
- </p>
-
- <p>
- If the changelog format which is being parsed always or
- almost always leaves a blank line between individual
- change notes these blank lines should be stripped out,
- so as to make the resulting output compact.
- </p>
-
- <p>
- If the changelog format does not contain date or package
- name information this information should be omitted from
- the output. The parser should not attempt to synthesize
- it or find it from other sources.
- </p>
-
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
-
- <p>
- A changelog parser may not interact with the user at
- all.
- </p>
- </sect2>
- </sect1>
-
<sect1 id="pkg-srcsubstvars">
<heading><file>debian/substvars</file> and variable substitutions</heading>