man/deb-changes.pod

   1 # dpkg manual page - deb-changes(5)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2010 Russ Allbery <rra@debian.org>
   5 # Copyright © 2015 Guillem Jover <guillem@debian.org>
   6 #
   7 # This is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  19
  20 =encoding utf8
  21
  22 =head1 NAME
  23
  24 deb-changes - Debian upload changes control file format
  25
  26 =head1 SYNOPSIS
  27
  28 I<filename>B<.changes>
  29
  30 =head1 DESCRIPTION
  31
  32 Each Debian upload is composed of a .changes control file, which
  33 contains a number of fields in L<deb822(5)> format.
  34
  35 Each field begins with a tag, such as
  36 B<Source>
  37 or
  38 B<Binary>
  39 (case insensitive), followed by a colon, and the body of the field
  40 (case sensitive unless stated otherwise).
  41 Fields are delimited only by field tags.
  42 In other words, field text may be multiple lines in length, but the
  43 installation tools will generally join lines when processing the body
  44 of the field (except in case of the multiline fields
  45 B<Description>, B<Changes>, B<Files>, B<Checksums-Sha1>
  46 and
  47 B<Checksums-Sha256>,
  48 see below).
  49
  50 The control data might be enclosed in an OpenPGP ASCII Armored signature,
  51 as specified in RFC4880.
  52
  53 =head1 FIELDS
  54
  55 =over
  56
  57 =item B<Format:> I<format-version> (required)
  58
  59 The value of this field declares the format version of the file.
  60 The syntax of the field value is a version number with a major and minor
  61 component.
  62 Backward incompatible changes to the format will bump the major version,
  63 and backward compatible changes (such as field additions) will bump the
  64 minor version.
  65 The current format version is B<1.8>.
  66
  67 =item B<Date:> I<release-date> (required)
  68
  69 The date the package was built or last edited.
  70 It must be in the same format as the date in a L<deb-changelog(5)>
  71 entry.
  72
  73 The value of this field is usually extracted from the I<debian/changelog>
  74 file.
  75
  76 =item B<Source:> I<source-name> [B<(>I<source-version>B<)>] (required)
  77
  78 The name of the source package.
  79 If the source version differs from the binary version, then the
  80 I<source-name> will be followed by a I<source-version> in parenthesis.
  81 This can happen when the upload is a binary-only non-maintainer upload.
  82
  83 =item B<Binary:> I<binary-package-list> (required in context)
  84
  85 This folded field is a space-separated list of binary packages to upload.
  86 If the upload is source-only, then the field is omitted (since dpkg 1.19.3).
  87
  88 =item B<Architecture:> I<arch-list>
  89
  90 Lists the architectures of the files currently being uploaded.
  91 Common architectures are B<amd64>, B<armel>, B<i386>, etc.
  92 Note that the B<all> value is meant for packages that are architecture
  93 independent.
  94 If the source for the package is also being uploaded, the special entry
  95 B<source> is also present.
  96 Architecture wildcards must never be present in the list.
  97
  98 =item B<Version:> I<version-string> (required)
  99
 100 Typically, this is the original package's version number in whatever form
 101 the program's author uses.
 102 It may also include a Debian revision number (for non-native packages).
 103 The exact format and sorting algorithm are described in
 104 L<deb-version(7)>.
 105
 106 =item B<Distribution:> I<distribution>s (required)
 107
 108 Lists one or more space-separated distributions where this version should
 109 be installed when it is uploaded to the archive.
 110
 111 =item B<Urgency:> I<urgency> (recommended)
 112
 113 The urgency of the upload.
 114 The currently known values, in increasing order of urgency, are:
 115 B<low>, B<medium>, B<high>, B<critical> and B<emergency>.
 116
 117 =item B<Maintainer:> I<fullname-email> (required)
 118
 119 Should be in the format “Joe Bloggs E<lt>jbloggs@example.orgE<gt>”, and is
 120 typically the person who created the package, as opposed to the author of
 121 the software that was packaged.
 122
 123 =item B<Changed-By:> I<fullname-email>
 124
 125 Should be in the format “Joe Bloggs E<lt>jbloggs@example.orgE<gt>”, and is
 126 typically the person who prepared the package changes for this release.
 127
 128 =item B<Description:> (recommended)
 129
 130 =item S< >I<binary-package-name> B<-> I<binary-package-summary>
 131
 132 This multiline field contains a list of binary package names followed by
 133 a space, a dash (‘B<->’) and their possibly truncated short
 134 descriptions.
 135 If the upload is source-only, then the field is omitted (since dpkg 1.19.3).
 136
 137 =item B<Closes:> I<bug-number-list>
 138
 139 A space-separated list of bug report numbers for bug reports that have been
 140 resolved with this upload.
 141 The distribution archive software might use this field to automatically
 142 close the referred bug numbers in the distribution bug tracking system.
 143
 144 =item B<Binary-Only: yes>
 145
 146 This field denotes that the upload is a binary-only non-maintainer build.
 147 It originates from the B<binary-only=yes> key/value from the changelog
 148 metadata entry.
 149
 150 =item B<Built-For-Profiles:> I<profile-list>
 151
 152 This field specifies a whitespace separated list of build profiles that
 153 this upload was built with.
 154
 155 =item B<Changes:> (required)
 156
 157 =item S< >I<changelog-entries>
 158
 159 This multiline field contains the concatenated text of all changelog
 160 entries that are part of the upload.
 161 To make this a valid multiline field empty lines are replaced with a
 162 single full stop (‘.’) and all lines are indented by one space
 163 character.
 164 The exact content depends on the changelog format.
 165
 166 =item B<Files:> (required)
 167
 168 =item S< >I<md5sum> I<size> I<section> I<priority> I<filename>
 169
 170 This multiline field contains a list of files with an md5sum, size, section
 171 and priority for each one.
 172
 173 The first line of the field value (the part on the same line as the field
 174 name followed by a colon) is always empty.
 175 The content of the field is expressed as continuation lines, one line per file.
 176 Each line consists of space-separated entries describing the file:
 177 the md5sum, the file size, the file section, the file priority, and
 178 the file name.
 179
 180 This field lists all files that make up the upload.
 181 The list of files in this field must match the list of files in the
 182 other related B<Checksums> fields.
 183
 184 B<Note>: The MD5 checksum is considered weak,
 185 and should never be assumed to be sufficient for secure verification,
 186 but this field cannot be omitted as it provides metadata not available
 187 anywhere else.
 188
 189 =item B<Checksums-Sha1:> (required, weak)
 190
 191 =item B<Checksums-Sha256:> (required, strong)
 192
 193 =item S< >I<checksum> I<size> I<filename>
 194
 195 These multiline fields contain a list of files with a checksum and size
 196 for each one.
 197 These fields have the same syntax and differ only in the checksum algorithm
 198 used: SHA-1 for B<Checksums-Sha1> and SHA-256 for B<Checksums-Sha256>.
 199
 200 The first line of the field value (the part on the same line as the field
 201 name followed by a colon) is always empty.
 202 The content of the field is expressed as continuation lines, one line per file.
 203 Each line consists of space-separated entries describing the file:
 204 the checksum, the file size, and the file name.
 205
 206 These fields list all files that make up the upload.
 207 The list of files in these fields must match the list of files in the
 208 B<Files> field and the other related B<Checksums> fields.
 209
 210 B<Note>: The SHA-1 checksum is considered weak,
 211 and should never be assumed to be sufficient for secure verification.
 212
 213 =back
 214
 215 =head1 BUGS
 216
 217 The B<Files> field is inconsistent with the other B<Checksums> fields.
 218 The B<Changed-By> and B<Maintainer> fields have confusing names.
 219 The B<Distribution> field contains information about what is commonly
 220 referred to as a suite.
 221
 222 =head1 SEE ALSO
 223
 224 L<deb822(5)>,
 225 L<deb-src-control(5)>,
 226 L<deb-version(7)>.