ChangeLog file format

Submitted by Alexis Wilke on Wed, 06/19/2013 - 02:07
Authoritative Source:
Debian changelog
To Install on your Debian system:
sudo apt-get install debian-policy

Introduction

When working on a project, it is customary to write down information about what changes you make between versions; fixed a bug, added a feature, finished the implementation of a feature, etc.

This information is saved in what is called a ChangeLog file. In the wpkg environment we expect the file to be defined as:

wpkg/changelog

(i.e. if you are in the root directory of your project, the ls -l wpkg/changelog should show you that file.)

The file is UTF-8 text which includes a header, change logs, and a footer for each version of the project. So a file is a repeat of:

package-name (version) category; param=<value>
       (optional empty lines)
  * Change A(1)
  * Change A(2)
       (empty line to separate groups)
  * Change B(1)
  * Change B(2)
       (optional empty lines)
 -- User Name <user@example.com>  Date

Note that empty lines in themselves are ignored, however, when used to separate groups, they are required.

Header

The header is composed of the package name, the package version, the categorization of the package, and a set of comma separated parameters.

The header text starts in the very first column (no spaces before the package name.)

Package Name

The name of the package, exactly the same way as it appears in the Package field of your control.info file of the package runtime component (i.e. the component with the asterisk.)

In this example:

Sub-Package: runtime*, development, documentation
Package/runtime: wpkg

the package name is wpkg. The Package/development and Package/documentation entries are ignored (although they get validated.)

Version

The Version of the package. It is expected that your control.info file will not define this field since it comes from the changelog file. It is up to you to define it in both places or not. If so, then each time you bump your version up, you will have to edit both places.

Any valid Debian version is accepted. Note that in the changelog file, the version is written between parenthesis without spaces before or after the version.

Category

The Category field is defined as a list of categories separated by slash characters. Each category is defined as:

  • Distribution
  • Area
  • Section
  • Sub-Section

These are used to select the location where the package appears in your repository. It is also used by applications to display the package under a heading corresponding to those categories. This ease the search of a package, usually.

The Distribution is also copied in the Distribution field if also valid in Debian.

The Area and Section are also copied to the Section field if also valid in Debian. Some of the names may be modified by the package to better match the Debian environment. If the Section matches, but not the Area, then only the Section is copied.

The Section and Sub-Section are also copied to the X-PrimarySection and X-SecondarySection fields. This ease the use of those two terms in tools such as pkg_explorer.

Parameters

The header ends with a list of comma separated parameters defined as:

<parameter name>=<value>

Since the parameters are separated by commas, it is not possible to use commas anywhere else (there is no way to escape a character or using quotes.)

At this time, only the value of the Urgency field is recognized in this list of parameters. For example:

urgency=medium

Debian only supports that field.

Changes

The list of changes are things that you modified in your project. Each line starts with exactly 2 spaces, an asterisk, and another space before the text of your change. The text of the change is free form.

All the change logs are copied to the Changes field of your source package and it will be duplicated in the binary packages.

Bugs

Although the log entries are free form, we recognize:

  • Closes: bug field; and
  • The special colon introducer syntax.

The "Closes:" field introducer must be at the end of the change text and be followed by a comma separated list of bugs that were fixed. If bug numbers start with e hash (#) character, it gets removed. Start and end spaces are trimmer. Any number of bugs can be specified in this case.

The colon introducer is a set of letters, digits, dashes, and other characters except spaces and commas up to the first colon character that represents a bug number. If the set of characters starts with a hash (#) character, it is removed. Only one bug can be specified in this way.

For example, you work on bug WPKG-123, you make a note about it as one of the following two syntaxes:

  * WPKG-123: fixed bug
  * Fixed bug, Closes: WPKG-123, #45-9

The changelog parser will detect these entries and add them to the Closes field of your control file.

First Version

In the very first version of your package, you may want to use something such as:

  * First Revision

Since the list of changes cannot be empty, you've got to have at least one line and this is the usual line used for this purpose.

Groups

Changes can be organized in groups. Each group is separated by an empty line:

  * Group 1
  * More of Group 1

  * Group 2
  * More in Group 2
  * Even more in Group 2

There is no special meaning to groups, if you work on several new features, several bugs, etc. you may want to make use of groups to clearly show what corresponds to what.

Footer

The footer starts with one space, two dashes (-), and another space before the name and email address of the maintainer of the package. Then it ends with two spaces followed by the date written in a very specific format.

Email

The user name and email address must be defined exactly as you would define such in an Internal Message. This being said, there is one limit: the user name in that email address cannot include two spaces in a row.

Date

The date format is defined by Debian as:

DDD, dd mmm yyyy HH:MM:SS +ZZZZ

Where:

  • DDD is the 3 letter day (Sun, Mon, Tue, Wed, Thu, Fri, Sat),
  • dd is the day of the month (01 to 31),
  • mmm is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec),
  • yyyy is the year including the century,
  • HH is the hour,
  • MM is the minute,
  • SS is the second,
  • +ZZZZ is the time zone defined as an offset between your timezone and the Universal Time Coordinate. The offset may be negative.