(debian-policy.info)Debian changelog debian/changelog

---

Next: Copyright debian/copyright Prev: Changes to the upstream sources Up: Source packages

---

Enter node , (file) or (file)node

4.4 Debian changelog: ‘debian/changelog’
========================================

Every source package must include the Debian changelog file,
‘debian/changelog’.  Changes in the Debian version of the package should
be briefly explained in this file.  (1) This includes modifications made
in the Debian package compared to the upstream one as well as other
changes and updates to the package.  (2)

The format of the ‘debian/changelog’ allows the package building tools
to discover which version of the package is being built and find out
other release-specific information.

That format is a series of entries like this:

     package (version) distribution(s); urgency=urgency
       [optional blank line(s), stripped]
       * change details
       more change details
       [blank line(s), included in output of dpkg-parsechangelog]
       * even more change details
       [optional blank line(s), stripped]
     -- maintainer name <email address>[two spaces]  date

‘package’ and ‘version’ are the source package name and version number.

‘distribution(s)’ lists the distributions where this version should be
installed when it is uploaded - it is copied to the ‘Distribution’ field
in the ‘.changes’ file.  See Note: Distribution.

‘urgency’ is the value for the ‘Urgency’ field in the ‘.changes’ file
for the upload (see Note: Urgency.).  It is not possible to specify
an urgency containing commas; commas are used to separate
‘keyword=value’ settings in the ‘dpkg’ changelog format (though there is
currently only one useful keyword, ‘urgency’).

The change details may in fact be any series of lines starting with at
least two spaces, but conventionally each change starts with an asterisk
and a separating space and continuation lines are indented so as to
bring them in line with the start of the text above.  Blank lines may be
used here to separate groups of changes, if desired.

If this upload resolves bugs recorded in the Bug Tracking System (BTS),
they may be automatically closed on the inclusion of this package into
the Debian archive by including the string: ‘closes: Bug#nnnnn’ in the
change details.  (3) This information is conveyed via the ‘Closes’ field
in the ‘.changes’ file (see Note: Closes.).

The maintainer name and email address used in the changelog should be
the details of the person who prepared this release of the package.
They are `not' necessarily those of the uploader or usual package
maintainer.  (4) The information here will be copied to the ‘Changed-By’
field in the ‘.changes’ file (see Note: Changed-By.), and then later
used to send an acknowledgement when the upload has been installed.

The date has the following format (5) (compatible and with the same
semantics of RFC 2822 and RFC 5322):

     day-of-week, dd month yyyy hh:mm:ss +zzzz

where:

   - ‘day-of week’ is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun

   - ‘dd’ is a one- or two-digit day of the month (01-31)

   - ‘month’ is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep,
     Oct, Nov, Dec

   - ‘yyyy’ is the four-digit year (e.g.  2010)

   - ‘hh’ is the two-digit hour (00-23)

   - ‘mm’ is the two-digit minutes (00-59)

   - ‘ss’ is the two-digit seconds (00-60)

   - 
     ‘+zzzz’ or ‘-zzzz’ is the time zone offset from Coordinated

          Universal Time (UTC). “+” indicates that the time is ahead of
          (i.e., east of) UTC and “-” indicates that the time is behind
          (i.e., west of) UTC. The first two digits indicate the hour
          difference from UTC and the last two digits indicate the
          number of additional minutes difference from UTC. The last two
          digits must be in the range 00-59.

The first “title” line with the package name must start at the left hand
margin.  The “trailer” line with the maintainer and date details must be
preceded by exactly one space.  The maintainer details and the date must
be separated by exactly two spaces.

The entire changelog must be encoded in UTF-8.

For more information on placement of the changelog files within binary
packages, please see Note: Changelog files and release notes.

   ---------- Footnotes ----------

   (1) Mistakes in changelogs are usually best rectified by making a new
changelog entry rather than “rewriting history” by editing old changelog
entries.

   (2) Although there is nothing stopping an author who is also the
Debian maintainer from using this changelog for all their changes, it
will have to be renamed if the Debian and upstream maintainers become
different people.  In such a case, however, it might be better to
maintain the package as a non-native package.

   (3) To be precise, the string should match the following Perl regular
expression:

     /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i

Then all of the bug numbers listed will be closed by the archive
maintenance software (‘dak’) using the version of the changelog entry.

   (4) In the case of a sponsored upload, the uploader signs the files,
but the changelog maintainer name and address are those of the person
who prepared this release.  If the preparer of the release is not one of
the usual maintainers of the package (as listed in the
:ref:‘`Maintainer’ <#s-f-Maintainer‘ or ‘`Uploaders’ <s-f-Uploaders>‘
control fields of the package), the first line of the changelog is
conventionally used to explain why a non-maintainer is uploading the
package.  The Debian Developer’s Reference (see *note Related documents:
11.) documents the conventions used.

   (5) This is the same as the format generated by ‘date -R’.