man/deb-changelog.pod

   1 # dpkg manual page - deb-changelog(5)
   2 #
   3 # Copyright © 1996-1998 Ian Jackson and Christian Schwarz
   4 # Copyright © 1998, 2001 Manoj Srivastava <srivasta@debian.org>
   5 # Copyright © 2001 Julian Gilbey <jdg@debian.org>
   6 # Copyright © 2003 Josip Rodin <joy@debian.org>
   7 # Copyright © 2008, 2010 Russ Allbery <rra@debian.org>
   8 # Copyright © 2010 Charles Plessy <plessy@debian.org>
   9 # Copyright © 2014 Bill Allombert <ballombe@debian.org>
  10 # Copyright © 2015-2017 Guillem Jover <guillem@debian.org>
  11 #
  12 # This is free software; you can redistribute it and/or modify
  13 # it under the terms of the GNU General Public License as published by
  14 # the Free Software Foundation; either version 2 of the License, or
  15 # (at your option) any later version.
  16 #
  17 # This is distributed in the hope that it will be useful,
  18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 # GNU General Public License for more details.
  21 #
  22 # You should have received a copy of the GNU General Public License
  23 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  24
  25 =encoding utf8
  26
  27 =head1 NAME
  28
  29 deb-changelog - dpkg source packages' changelog file format
  30
  31 =head1 SYNOPSIS
  32
  33 B<debian/changelog>
  34
  35 =head1 DESCRIPTION
  36
  37 Changes in the packaged version of a project are explained in the
  38 changelog file I<debian/changelog>.
  39 This includes modifications made in the source package compared to the
  40 upstream one as well as other changes and updates to the package.
  41
  42 The format of the I<debian/changelog> allows the package building
  43 tools to discover which version of the package is being built and find
  44 out other release-specific information.
  45
  46 That format is a series of entries like this:
  47
  48 Z<>
  49  I<package> (I<version>) I<distributions>; I<metadata>
  50           [optional blank line(s), stripped]
  51   * I<change-details>
  52     I<more-change-details>
  53           [blank line(s), included in L<dpkg-parsechangelog(1)> output]
  54   * I<even-more-change-details>
  55           [optional blank line(s), stripped]
  56   -- I<maintainer-name> <I<email-address>>  I<date>
  57
  58 I<package> and I<version> are the source package name and version
  59 number.
  60 I<version> is delimited by parenthesis U+00028 ‘B<(>’ and
  61 U+0029 ‘B<)>’.
  62
  63 I<distributions> lists one or more space-separated distributions where
  64 this version should be installed when it is uploaded; it is copied to the
  65 B<Distribution> field in the I<.changes> file.
  66 I<distributions> must be terminated by a semicolon (U+003B ‘B<;>’).
  67
  68 I<metadata> lists zero or more comma-separated I<keyword>=I<value>
  69 items.
  70 Each keyword can contain only minus and case insensitive alphanumeric
  71 characters, as they need to be mapped to L<deb822(5)> field names.
  72 The only I<keyword>s currently supported by B<dpkg> are:
  73
  74 =over
  75
  76 =item B<urgency>
  77
  78 Its value is used for the B<Urgency> field in the
  79 I<.changes> file for the upload.
  80
  81 =item B<binary-only>
  82
  83 With a B<yes> value, it is used to denote that this
  84 changelog entry is for a binary-only non-maintainer upload (an automatic
  85 binary rebuild with the only change being the changelog entry).
  86
  87 =back
  88
  89 The change details may in fact be any series of lines starting with
  90 at least two spaces (U+0020 B<SPACE>), but conventionally each
  91 change starts with an
  92 asterisk and a separating space and continuation lines are indented
  93 so as to bring them in line with the start of the text above.
  94 Blank lines may be used here to separate groups of changes, if desired.
  95
  96 If this upload resolves bugs recorded in the distribution bug tracking
  97 system, they may be automatically closed on the inclusion of this
  98 package into the distribution archive by including the string:
  99
 100 =over
 101
 102 B<Closes: #>I<nnnnn>
 103
 104 =back
 105
 106 in the change details, where B<#>I<nnnnn> is the bug number.
 107 The exact Perl regular expression is:
 108
 109 =over
 110
 111 B</closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i>
 112
 113 =back
 114
 115 That is, the string should consist of the word B<closes:> followed by
 116 a comma-separated list of bug numbers.
 117 Bug numbers may be preceded by the word B<bug> and/or a B<#> sign,
 118 as in C<Closes: 42, bug#43, #44, bug 45>.
 119 The words B<closes:> and B<bug> are not case sensitive.
 120 The list of bug numbers may span multiple lines.
 121
 122 This information is conveyed via the B<Closes> field in the I<.changes>
 123 file.
 124 Where, depending on the archive maintenance software, all the bug numbers
 125 listed might get automatically closed.
 126
 127 The maintainer name and email address used in the changelog should be the
 128 details of the person who prepared this release of the package.
 129 They are B<not> necessarily those of the uploader or usual package
 130 maintainer.
 131 The information here will be copied to the B<Changed-By> field in the
 132 I<.changes> file, and then later might be used to send an acknowledgment
 133 when the upload has been installed in the distribution archive.
 134
 135 The I<date> has the following format (compatible and with the same
 136 semantics of RFC2822 and RFC5322, or what «date -R» generates):
 137
 138 =over
 139
 140 I<day-of-week>B<,> I<dd> I<month> I<yyyy> I<hh>B<:>I<mm>B<:>I<ss> B<+>I<zzzz>
 141
 142 =back
 143
 144 where:
 145
 146 =over
 147
 148 =item I<day-of-week>
 149
 150 Is one of:
 151 B<Mon>, B<Tue>, B<Wed>, B<Thu>, B<Fri>, B<Sat>, B<Sun>.
 152
 153 =item I<dd>
 154
 155 Is a one- or two-digit day of the month (B<01>-B<31>), where the leading
 156 zero is optional, but conventionally does not get omitted.
 157
 158 =item I<month>
 159
 160 Is one of:
 161 B<Jan>, B<Feb>, B<Mar>, B<Apr>, B<May>, B<Jun>, B<Jul>, B<Aug>,
 162 B<Sep>, B<Oct>, B<Nov>, B<Dec>.
 163
 164 =item I<yyyy>
 165
 166 Is the four-digit year (e.g. 2010).
 167
 168 =item I<hh>
 169
 170 Is the two-digit hour (B<00>-B<23>).
 171
 172 =item I<mm>
 173
 174 Is the two-digit minutes (B<00>-B<59>).
 175
 176 =item I<ss>
 177
 178 Is the two-digit seconds (B<00>-B<60>).
 179
 180 =item [B<+->]I<zzzz>
 181
 182 Is the time zone offset from Coordinated Universal Time (UTC).
 183 ‘B<+>’ indicates that the time is ahead of (i.e., east of) UTC and
 184 ‘B<->’ indicates that the time is behind (i.e., west of) UTC.
 185 The first two digits indicate the hour difference from UTC and the last
 186 two digits indicate the number of additional minutes difference from UTC.
 187 The last two digits must be in the range B<00>-B<59>.
 188
 189 =back
 190
 191 The first “title” line with the package name must start at the left
 192 hand margin.
 193 The “trailer” line with the maintainer and date details must be
 194 preceded by exactly one space (U+0020 B<SPACE>).
 195 The maintainer details and the date must be separated by exactly two
 196 spaces (U+0020 B<SPACE>).
 197 Each part of the I<date> can be separated by one or more spaces
 198 (U+0020 B<SPACE>), except after the comma where it can be separated
 199 by zero or more spaces (U+0020 B<SPACE>).
 200
 201 Any line that consists entirely (i.e., no leading whitespace) of B<#>
 202 or B</* */> style comments or RCS keywords.
 203
 204 Vim modelines or Emacs local variables, and ancient changelog entries with
 205 other formats at the end of the file should be accepted and preserved on
 206 output, but their contents might be otherwise ignored and parsing stopped
 207 at that point.
 208
 209 The entire changelog must be encoded in UTF-8.
 210
 211 =head1 FILES
 212
 213 =over
 214
 215 =item I<debian/changelog>
 216
 217 =back
 218
 219 =head1 EXAMPLES
 220
 221  dpkg (1.17.18) unstable; urgency=low
 222
 223   [ Guillem Jover ]
 224   * Handle empty minimum versions when initializing dependency versions,
 225     as the code is mapping the minimum version 0 to '' to avoid outputting
 226     useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
 227
 228   [ Updated programs translations ]
 229   * Catalan (Guillem Jover).
 230
 231   [ Updated dselect translations ]
 232   * Catalan (Guillem Jover).
 233   * German (Sven Joachim).
 234
 235   -- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200
 236
 237 =head1 SEE ALSO
 238
 239 L<deb822(5)>,
 240 L<deb-changes(5)>,
 241 L<deb-version(7)>,
 242 L<dpkg-parsechangelog(1)>.