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 B<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 B<deb822>(5) field names.
  72 The only I<keyword>s currently supported by B<dpkg> are B<urgency>
  73 and B<binary-only>.
  74 B<urgency>'s value is used for the B<Urgency> field in the
  75 I<.changes> file for the upload.
  76 B<binary-only> with a B<yes> value, is used to denote that this
  77 changelog entry is for a binary-only non-maintainer upload (an automatic
  78 binary rebuild with the only change being the changelog entry).
  79
  80 The change details may in fact be any series of lines starting with
  81 at least two spaces (U+0020 B<SPACE>), but conventionally each
  82 change starts with an
  83 asterisk and a separating space and continuation lines are indented
  84 so as to bring them in line with the start of the text above.
  85 Blank lines may be used here to separate groups of changes, if desired.
  86
  87 If this upload resolves bugs recorded in the distribution bug tracking
  88 system, they may be automatically closed on the inclusion of this
  89 package into the distribution archive by including the string:
  90
  91 =over
  92
  93 B<Closes: #>I<nnnnn>
  94
  95 =back
  96
  97 in the change details, where B<#>I<nnnnn> is the bug number.
  98 The exact Perl regular expression is:
  99
 100 =over
 101
 102 B</closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i>
 103
 104 =back
 105
 106 That is, the string should consist of the word B<closes:> followed by
 107 a comma-separated list of bug numbers.
 108 Bug numbers may be preceded by the word B<bug> and/or a B<#> sign,
 109 as in C<Closes: 42, bug#43, #44, bug 45>.
 110 The words B<closes:> and B<bug> are not case sensitive.
 111 The list of bug numbers may span multiple lines.
 112
 113 This information is conveyed via the B<Closes> field in the I<.changes>
 114 file.
 115 Where, depending on the archive maintenance software, all the bug numbers
 116 listed might get automatically closed.
 117
 118 The maintainer name and email address used in the changelog should be the
 119 details of the person who prepared this release of the package.
 120 They are B<not> necessarily those of the uploader or usual package
 121 maintainer.
 122 The information here will be copied to the B<Changed-By> field in the
 123 I<.changes> file, and then later might be used to send an acknowledgment
 124 when the upload has been installed in the distribution archive.
 125
 126 The I<date> has the following format (compatible and with the same
 127 semantics of RFC2822 and RFC5322, or what «date -R» generates):
 128
 129 =over
 130
 131 I<day-of-week>B<,> I<dd> I<month> I<yyyy> I<hh>B<:>I<mm>B<:>I<ss> B<+>I<zzzz>
 132
 133 =back
 134
 135 where:
 136
 137 =over
 138
 139 =item I<day-of-week>
 140
 141 Is one of:
 142 B<Mon>, B<Tue>, B<Wed>, B<Thu>, B<Fri>, B<Sat>, B<Sun>.
 143
 144 =item I<dd>
 145
 146 Is a one- or two-digit day of the month (B<01>-B<31>), where the leading
 147 zero is optional, but conventionally does not get omitted.
 148
 149 =item I<month>
 150
 151 Is one of:
 152 B<Jan>, B<Feb>, B<Mar>, B<Apr>, B<May>, B<Jun>, B<Jul>, B<Aug>,
 153 B<Sep>, B<Oct>, B<Nov>, B<Dec>.
 154
 155 =item I<yyyy>
 156
 157 Is the four-digit year (e.g. 2010).
 158
 159 =item I<hh>
 160
 161 Is the two-digit hour (B<00>-B<23>).
 162
 163 =item I<mm>
 164
 165 Is the two-digit minutes (B<00>-B<59>).
 166
 167 =item I<ss>
 168
 169 Is the two-digit seconds (B<00>-B<60>).
 170
 171 =item [B<+->]I<zzzz>
 172
 173 Is the time zone offset from Coordinated Universal Time (UTC).
 174 ‘B<+>’ indicates that the time is ahead of (i.e., east of) UTC and
 175 ‘B<->’ indicates that the time is behind (i.e., west of) UTC.
 176 The first two digits indicate the hour difference from UTC and the last
 177 two digits indicate the number of additional minutes difference from UTC.
 178 The last two digits must be in the range B<00>-B<59>.
 179
 180 =back
 181
 182 The first “title” line with the package name must start at the left
 183 hand margin.
 184 The “trailer” line with the maintainer and date details must be
 185 preceded by exactly one space (U+0020 B<SPACE>).
 186 The maintainer details and the date must be separated by exactly two
 187 spaces (U+0020 B<SPACE>).
 188 Each part of the I<date> can be separated by one or more spaces
 189 (U+0020 B<SPACE>), except after the comma where it can be separated
 190 by zero or more spaces (U+0020 B<SPACE>).
 191
 192 Any line that consists entirely (i.e., no leading whitespace) of B<#>
 193 or B</* */> style comments or RCS keywords.
 194
 195 Vim modelines or Emacs local variables, and ancient changelog entries with
 196 other formats at the end of the file should be accepted and preserved on
 197 output, but their contents might be otherwise ignored and parsing stopped
 198 at that point.
 199
 200 The entire changelog must be encoded in UTF-8.
 201
 202 =head1 FILES
 203
 204 =over
 205
 206 =item I<debian/changelog>
 207
 208 =back
 209
 210 =head1 EXAMPLES
 211
 212  dpkg (1.17.18) unstable; urgency=low
 213
 214   [ Guillem Jover ]
 215   * Handle empty minimum versions when initializing dependency versions,
 216     as the code is mapping the minimum version 0 to '' to avoid outputting
 217     useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
 218
 219   [ Updated programs translations ]
 220   * Catalan (Guillem Jover).
 221
 222   [ Updated dselect translations ]
 223   * Catalan (Guillem Jover).
 224   * German (Sven Joachim).
 225
 226   -- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200
 227
 228 =head1 SEE ALSO
 229
 230 B<deb822>(5),
 231 B<deb-version>(7),
 232 B<deb-changes>(5),
 233 B<dpkg-parsechangelog>(1).