- <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
- </heading>
-
- <p>
- In a <file>.changes</file> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be installed. Valid distributions are determined by the
- archive maintainers.<footnote>
- Current distribution names are:
- <taglist compact="compact">
- <tag><em>stable</em></tag>
- <item>
- <p>
- This is the current `released' version of Debian
- GNU/Linux. Once the distribution is
- <em>stable</em> only security fixes and other
- major bug fixes are allowed. When changes are
- made to this distribution, the release number is
- increased (for example: 2.2r1 becomes 2.2r2 then
- 2.2r3, etc).
- </p>
- </item>
-
- <tag><em>unstable</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>developmental</em> part of the Debian
- distribution tree. New packages, new upstream
- versions of packages and bug fixes go into the
- <em>unstable</em> directory tree. Download from
- this distribution at your own risk.
- </p>
- </item>
-
- <tag><em>testing</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>testing</em> part of the Debian distribution
- tree. It receives its packages from the
- unstable distribution after a short time lag to
- ensure that there are no major issues with the
- unstable packages. It is less prone to breakage
- than unstable, but still risky. It is not
- possible to upload packages directly to
- <em>testing</em>.
- </p>
- </item>
-
- <tag><em>frozen</em></tag>
- <item>
- <p>
- From time to time, the <em>testing</em>
- distribution enters a state of `code-freeze' in
- anticipation of release as a <em>stable</em>
- version. During this period of testing only
- fixes for existing or newly-discovered bugs will
- be allowed. The exact details of this stage are
- determined by the Release Manager.
- </p>
- </item>
-
- <tag><em>experimental</em></tag>
- <item>
- <p>
- The packages with this distribution value are
- deemed by their maintainers to be high
- risk. Oftentimes they represent early beta or
- developmental packages from various sources that
- the maintainers want people to try, but are not
- ready to be a part of the other parts of the
- Debian distribution tree. Download at your own
- risk.
- </p>
- </item>
- </taglist>
-
- You should list <em>all</em> distributions that the
- package should be installed into.
- </footnote>
- </p>
- </sect1>
-
-
- </sect>
- </chapt>
-
- <chapt id="versions"><heading>Version numbering</heading>
-
- <p>
- Every package has a version number recorded in its
- <tt>Version</tt> control file field.
- </p>
-
- <p>
- The package management system imposes an ordering on version
- numbers, so that it can tell whether packages are being up- or
- downgraded and so that package system front end applications
- can tell whether a package it finds available is newer than
- the one installed on the system. The version number format
- has the most significant parts (as far as comparison is
- concerned) at the beginning.
- </p>
-
- <p>
- The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
- </p>
-
- <p>
- The three components here are:
- <taglist>
- <tag><var>epoch</var></tag>
- <item>
- <p>
- This is a single (generally small) unsigned integer. It
- may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream_version</var> may not
- contain any colons.
- </p>
-
- <p>
- It is provided to allow mistakes in the version numbers
- of older versions of a package, and also a package's
- previous version numbering schemes, to be left behind.
- </p>
- </item>
-
- <tag><var>upstream_version</var></tag>
- <item>
- <p>
- This is the main part of the version number. It is
- usually the version number of the original (`upstream')
- package from which the <file>.deb</file> file has been made,
- if this is applicable. Usually this will be in the same
- format as that specified by the upstream author(s);
- however, it may need to be reformatted to fit into the
- package management system's format and comparison
- scheme.
- </p>
-
- <p>
- The comparison behavior of the package management system
- with respect to the <var>upstream_version</var> is
- described below. The <var>upstream_version</var>
- portion of the version number is mandatory.
- </p>
-
- <p>
- The <var>upstream_version</var> may contain only
- alphanumerics<footnote>
- <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
- </footnote>
- and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
- <tt>:</tt> (full stop, plus, hyphen, colon) and should
- start with a digit. If there is no
- <var>debian_revision</var> then hyphens are not allowed;
- if there is no <var>epoch</var> then colons are not
- allowed.</p>
- </item>
-
- <tag><var>debian_revision</var></tag>
- <item>
- <p>
- This part of the version number specifies the version of
- the Debian package based on the upstream version. It
- may contain only alphanumerics and the characters
- <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
- compared in the same way as the
- <var>upstream_version</var> is.
- </p>
-
- <p>
- It is optional; if it isn't present then the
- <var>upstream_version</var> may not contain a hyphen.
- This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one `debianization'
- of it and therefore no revision indication is required.
- </p>
-
- <p>
- It is conventional to restart the
- <var>debian_revision</var> at <tt>1</tt> each time the
- <var>upstream_version</var> is increased.
- </p>
-
- <p>
- The package management system will break the version
- number apart at the last hyphen in the string (if there
- is one) to determine the <var>upstream_version</var> and
- <var>debian_revision</var>. The absence of a
- <var>debian_revision</var> compares earlier than the
- presence of one (but note that the
- <var>debian_revision</var> is the least significant part
- of the version number).
- </p>
- </item>
- </taglist>
- </p>
-
- <p>
- The <var>upstream_version</var> and <var>debian_revision</var>
- parts are compared by the package management system using the
- same algorithm:
- </p>
-
- <p>
- The strings are compared from left to right.
- </p>
-
- <p>
- First the initial part of each string consisting entirely of
- non-digit characters is determined. These two parts (one of
- which may be empty) are compared lexically. If a difference
- is found it is returned. The lexical comparison is a
- comparison of ASCII values modified so that all the letters
- sort earlier than all the non-letters.
- </p>
-
- <p>
- Then the initial part of the remainder of each string which
- consists entirely of digit characters is determined. The
- numerical values of these two parts are compared, and any
- difference found is returned as the result of the comparison.
- For these purposes an empty string (which can only occur at
- the end of one or both version strings being compared) counts
- as zero.
- </p>
-
- <p>
- These two steps (comparing and removing initial non-digit
- strings and initial digit strings) are repeated until a
- difference is found or both strings are exhausted.
- </p>
-
- <p>
- Note that the purpose of epochs is to allow us to leave behind
- mistakes in version numbering, and to cope with situations
- where the version numbering scheme changes. It is
- <em>not</em> intended to cope with version numbers containing
- strings of letters which the package management system cannot
- interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
- silly orderings (the author of this manual has heard of a
- package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
- <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
- <tt>2</tt> and so forth).
- </p>
-
- <p>
- If an upstream package has problematic version numbers they
- should be converted to a sane form for use in the
- <tt>Version</tt> field.
- </p>
-
- <sect>
- <heading>Version numbers based on dates</heading>
- <p>
- In general, Debian packages should use the same version
- numbers as the upstream sources.</p>
-
- <p>
- However, in some cases where the upstream version number is
- based on a date (e.g., a development `snapshot' release) the
- package management system cannot handle these version
- numbers without epochs. For example, dpkg will consider
- `96May01' to be greater than `96Dec24'.</p>
-
- <p>
- To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: `19960501', `19961224'. It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.</p>
-
- <p>
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- <em>not</em> be changed.</p>
-
- <p>
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the `YYYYMMDD' format.</p>
- </sect>
- </chapt>
-
- <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
-
- <sect id="timestamps"><heading>Time Stamps</heading>
- <p>
- Maintainers should preserve the modification times of the
- upstream source files in a package, as far as is reasonably
- possible.<footnote>
- <p>
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
- </p>
- </footnote>
- </p>
- </sect>
-
- <sect id="debianrules"><heading><file>debian/rules</file> - the
- main building script</heading>
-
- <p>
- This file must be an executable makefile, and contains the
- package-specific recipes for compiling the package and
- building binary package(s) from the source.
- </p>