Chapter 4. Source packages

21

4.4 Debian changelog:

debian/changelog

Changes in the Debian version of the package should be briefly explained in the Debian

changelog file

debian/changelog

.

4

This includes modifications made in the Debian pack 

age compared to the upstream one as well as other changes and updates to the package.

5

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 `

Distribution

' on page

35

.

urgency is the value for the

Urgency

field in the

.changes

file for the upload (see `

Urgency

'

on page

36

). 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

).

6

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 automat 

ically closed on the inclusion of this package into the Debian archive by including the string:

closes:

Bug#

nnnnn

in the change details.

7

This information is conveyed via the

Closes

4

Mistakes in changelogs are usually best rectified by making a new changelog entry rather than  rewriting

history  by editing old changelog entries.

5

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.

6

Recognized urgency values are

low

,

medium

,

high

and

emergency

. They have an effect on how quickly a

package will be considered for inclusion into the

testing

distribution, and give an indication of the importance

of any fixes included in this upload.

7

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 script (

katie

), or in the case of an

NMU, marked as fixed.