chiark - git - mdw - dpkg/blob - man/deb-changes.man

   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 .TH deb\-changes 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  21 .nh
  22 .SH NAME
  23 deb\-changes \- Debian changes file format
  24 .
  25 .SH SYNOPSIS
  26 .IB filename .changes
  27 .
  28 .SH DESCRIPTION
  29 Each Debian upload is composed of a .changes control file, which
  30 contains a number of fields.
  31 Each field begins with a tag, such as
  32 .B Source
  33 or
  34 .B Binary
  35 (case insensitive), followed by a colon, and the body of the field.
  36 Fields are delimited only by field tags.
  37 In other words, field text may be multiple lines in length, but the
  38 installation tools will generally join lines when processing the body
  39 of the field (except in case of the multiline fields
  40 .BR Description ", " Changes ", " Files ", " Checksums\-Sha1
  41 and
  42 .BR Checksums\-Sha256 ,
  43 see below).
  44 .PP
  45 The control data might be enclosed in an OpenPGP ASCII Armored signature,
  46 as specified in RFC4880.
  47 .
  48 .SH FIELDS
  49 .TP
  50 .BR Format: " \fIformat-version\fP (required)"
  51 The value of this field declares the format version of the file.
  52 The syntax of the field value is a version number with a major and minor
  53 component.
  54 Backward incompatible changes to the format will bump the major version,
  55 and backward compatible changes (such as field additions) will bump the
  56 minor version.
  57 The current format version is \fB1.8\fP.
  58 .TP
  59 .BR Date: " \fIrelease-date\fP (required)"
  60 The date the package was built or last edited.
  61 It must be in the same format as the date in a \fBdeb\-changelog\fP(5)
  62 entry.
  63
  64 The value of this field is usually extracted from the \fIdebian/changelog\fP
  65 file.
  66 .TP
  67 .BR Source: " \fIsource-name\fP [\fB(\fP\fIsource-version\fP\fB)\fP] (required)"
  68 The name of the source package.
  69 If the source version differs from the binary version, then the
  70 \fIsource-name\fP will be followed by a \fIsource-version\fP in parenthesis.
  71 This can happen when the upload is a binary-only non-maintainer upload.
  72 .TP
  73 .BR Binary: " \fIbinary-package-list\fP (required)"
  74 This folded field is a space-separated list of binary packages to upload.
  75 .TP
  76 .BR Architecture: " \fIarch-list\fP"
  77 Lists the architectures of the files currently being uploaded.
  78 Common architectures are \fBamd64\fP, \fBarmel\fP, \fBi386\fP, etc.
  79 Note that the \fBall\fP value is meant for packages that are architecture
  80 independent.
  81 If the source for the package is also being uploaded, the special entry
  82 \fBsource\fP is also present.
  83 Architecture wildcards must never be present in the list.
  84 .TP
  85 .BR Version: " \fIversion-string\fP (required)"
  86 Typically, this is the original package's version number in whatever form
  87 the program's author uses.
  88 It may also include a Debian revision number (for non-native packages).
  89 The exact format and sorting algorithm are described in
  90 .BR deb\-version (5).
  91 .TP
  92 .BR Distribution: " \fIdistribution\fPs (required)"
  93 Lists one or more space-separated distributions where this version should
  94 be installed when it is uploaded to the archive.
  95 .TP
  96 .BR Urgency: " \fIurgency\fP (recommended)"
  97 The urgency of the upload.
  98 The currently known values, in increasing order of urgency, are:
  99 .BR low ", " medium ", " high ", " critical " and " emergency .
 100 .TP
 101 .BR Maintainer: " \fIfullname-email\fP (required)"
 102 Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is
 103 typically the person who created the package, as opposed to the author of
 104 the software that was packaged.
 105 .TP
 106 .BI Changed\-By: " fullname-email"
 107 Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is
 108 typically the person who prepared the package changes for this release.
 109 .TP
 110 .BR Description: " (recommended)"
 111 .TQ
 112 .RB " \fIbinary-package-name\fP " \fB\-\fP " \fIbinary-package-summary\fP"
 113 This multiline field contains a list of binary package names followed by
 114 a space, a dash (‘\fB\-\fP’) and their possibly truncated short
 115 descriptions.
 116 .TP
 117 .BI Closes: " bug-number-list"
 118 A space-separated list of bug report numbers that have been resolved with
 119 this upload.
 120 The distribution archive software might use this field to automatically
 121 close the referred bug numbers in the distribution bug tracking system.
 122 .TP
 123 .B Binary\-Only: yes
 124 This field denotes that the upload is a binary-only non-maintainer build.
 125 It originates from the \fBbinary\-only=yes\fP key/value from the changelog
 126 matadata entry.
 127 .TP
 128 .BI Built\-For\-Profiles: " profile-list"
 129 This field specifies a whitespace separated list of build profiles that
 130 this upload was built with.
 131 .TP
 132 .BR Changes: " (required)"
 133 .TQ
 134 .I " changelog-entries"
 135 This multiline field contains the concatenated text of all changelog
 136 entries that are part of the upload.
 137 To make this a valid multiline field empty lines are replaced with a
 138 single full stop (‘.’) and all lines are indented by one space
 139 character.
 140 The exact content depends on the changelog format.
 141 .TP
 142 .BR Files: " (required)"
 143 .TQ
 144 .RI " " md5sum " " size " " section " " priority " " filename
 145 This multiline field contains a list of files with an md5sum, size, section
 146 and priority for each one.
 147
 148 The first line of the field value (the part on the same line as the field
 149 name followed by a colon) is always empty.
 150 The content of the field is expressed as continuation lines, one line per file.
 151 Each line consists of space-separated entries describing the file:
 152 the md5sum, the file size, the file section, the file priority, and
 153 the file name.
 154
 155 This field lists all files that make up the upload.
 156 The list of files in this field must match the list of files in the
 157 other related \fBChecksums\fP fields.
 158 .TP
 159 .BR Checksums\-Sha1: " (required)"
 160 .TQ
 161 .BR Checksums\-Sha256: " (required)"
 162 .TQ
 163 .RI " " checksum " " size " " filename
 164 These multiline fields contain a list of files with a checksum and size
 165 for each one.
 166 These fields have the same syntax and differ only in the checksum algorithm
 167 used: SHA-1 for \fBChecksums\-Sha1\fP and SHA-256 for \fBChecksums\-Sha256\fP.
 168
 169 The first line of the field value (the part on the same line as the field
 170 name followed by a colon) is always empty.
 171 The content of the field is expressed as continuation lines, one line per file.
 172 Each line consists of space-separated entries describing the file:
 173 the checksum, the file size, and the file name.
 174
 175 These fields list all files that make up the upload.
 176 The list of files in these fields must match the list of files in the
 177 \fBFiles\fP field and the other related \fBChecksums\fP fields.
 178 .
 179 .\" .SH EXAMPLE
 180 .\" .RS
 181 .\" .nf
 182 .\"
 183 .\" .fi
 184 .\" .RE
 185 .
 186 .SH BUGS
 187 The \fBFiles\fP field is inconsistent with the other \fBChecksums\fP fields.
 188 The \fBChange\-By\fP and \fBMaintainer\fP fields have confusing names.
 189 The \fBDistribution\fP field contains information about what is commonly
 190 referred to as a suite.
 191 .SH SEE ALSO
 192 .BR deb\-src\-control (5),
 193 .BR deb\-version (5).