NAME
dchanges - build changes file for a Debian package
SYNOPSIS
dchanges [options] [overrides] [filename|spoverride ...]
DESCRIPTION
dchanges builds the changes file needed to register as a Debian package maintainer, or to place package files into the Debian distribution.
When dchanges is used to build a changes file, the user is normally dropped into an editor to edit the file and make any needed modifications or corrections to it. The -n option is provided to suppress this editing operation if desired. A syntax check is then performed on the file.
Changes files built by the dchanges program provide a standardized means for Debian package maintainers to interact with the Debian distribution maintainers. Since changes files may be processed by automated scripts, it is imperative that the formatting rules detailed in dchanges(5) be followed exactly. The dchanges program is a tool which aids in properly formatting changes files.
Once completed, changes files should be signed with the pgp(1) program and uploaded along with the package files, if any, to the Debian distribution maintenance site. dchanges will invoke pgp(1) to accomplish this unless the -p option is supplied to suppress this. Uploaded changes files will have their signatures verified, and will then be processed according to their contents.
ANNOUNCING UPLOADED PACKAGE FILES
Maintainers may build a changes file to announce uploaded package files by invoking dchanges as follows:
dchanges [options] [overrides] file_list
When uploading file the arch=name override should not general be used, dchanges can construct the Architecture field from the files supplied. The architecture name is defaulted to i386 for .deb files not providing an Architecture field, however this produces a warning message.
Files in file_list must all be named using standard Debian package naming conventions, and should have the form:
package_name-package_version.extension
package_name is the name of the package.
package_version is the upstream version number and Debian revision number of the package, separated by a - character. For packages specific to the Debian distribution or having no upstream maintainer, the Debian revision number might be arbitrarily set to 0 or 1 or omitted.
dchanges will infer the source package name and version from the first .deb file encountered, using the Source field.
Source: <src-name> [<version>]
If there is no Source field in the .deb file then the <src-name> and version are assumed to be the binary package name and version. If the <version> part of the Source field is omitted the version is assumed to be the binary package version.
Note: the version in the source field includes the debian revision.
If there are no .deb files then the overides src=, ver= etc. should be used (see below).
For the source maintainer, file_list should include one source tar(1) archive file having a .tar.gz extension and one compressed diff file having a .diff.gz extension. The .diff.gz file contains diffs between the more generic upstream sources and the Debian distribution sources. For packages specific to the Debian distribution, or packages without upstream sources, the .diff.gz file can be omitted.
Other package files having additional extensions not specified here may also be included by the source package maintainer, but this should occur only rarely and should be coordinated in advance with the Debian distribution maintainer.
For architecture maintainers, file_list must include at least one binary package file having a .deb extension per architecture. Binary file extensions should specify the architecture name immediately preceeding the .deb extension, and delimited from it by a . char (e.g., ed-0.2-5.sparc.diff). For uploaded .deb files section and priority hints are required. Use s=<sect> and p=<pri> to set the section/priority for the rest of the command line.
A changes file produced to upload package files might look something like the following:
Date: 01 May 96 22:06 UT Format: 1.4 Distribution: development Source: bc Architecture: source sparc Binary: bc dc Version: 1.03-8 Maintainer: Bill Mitchell <[email protected]> Description: bc: An arbitrary precision calculator language. dc: An arbitrary precision reverse-polish calculator. Priority: Routine Changes: This is a Changes field extension. Each line is indented by a single space character. . The line above indicates a blank line. Files: 293bb2e6033eeeaf685c03c30baef822 12345 math - bc-1.03-8.diff.gz bcf4ce45101d5fb4a2db0aed3d57df86 6789 math - bc-1.03-8.tar.gz a784e82d6a6c684618fd11bb6a4de300 12345 math important bc-1.03-8.sparc.deb 1ac1ed1dff4cfb69a699f5c69fcff179 13579 math important dc-1.03-8.sparc.deb
This changes file may then be signed with pgp(1) and uploaded along with the package files. At the option of the distribution maintainer, the uploaded package files may be accepted into the distribution. If this example changes file were accepted, and the bc package did not have registered source or sparc architecture maintainers, the maintainer named in the changes file would be registered as the Source and sparc Architecture maintainer for the package.
The changes file format is explained in detail in the dchanges(5) man page. The contents of the various fields is determined by dchanges while building the changes file, using information gleaned from invocation options and overrides and from the package files themselves.
REGISTERING AS A PACKAGE MAINTAINER
Maintainers wishing to begin work on a Debian package, but who do not expect to have the package ready for upload for some time may build a changes file to register as the source maintainer of that package by invoking dchanges as follows:
dchanges [options] src=package_name \\
maint="J. User <[email protected]>"
With this invocation, dchanges will build a changes file named package_name.changes similar to the following:
Date: 01 May 96 22:06 UT Format: 1.4 Source: package_name Maintainer: J. User <[email protected]> Description: no description provided Priority: Low
The package description should be manually inserted in this changes file. The maintainer name and email address should correspond with the pgp(1) public key for this package maintainer separately supplied to the distribution maintainer.
Normally, a summary package description placed entirely on the Description: line is sufficient at this point. If needed, extended description information extending over several lines may be added following this line. If extended description information lines are added, care should be exercised to assure that the format of these added lines conforms to the changes file format described in dchanges(5). In particular, the body lines in the extended description should be indented by a single blank char, and blank lines should be indicated by a line containing only a single blank char followed by a period (aka full-stop, or dot; i.e., " .").
At the option of the distribution maintainer, the named maintainer may be registered as an source maintainer of package_name.
Registered source maintainers are responsible for maintaining the source and diff files (and, in rare special cases, possibly other files as well) for Debian packages.
REGISTERING AS A PACKAGE ARCHITECTURE MAINTAINER
Maintainers wishing to support Debian package for one or more specific architectures may build a changes file to register as the maintainer of specific architectures for a package by invoking dchanges as follows:
dchanges [options] src=package maint=name \\
arch=architecture
Multiple architectures may be specified by enclosing the architecture argument in quotes and providing a blank-delimited list, as follows:
dchanges [options] src=package maint=name \\
arch="arch_1 arch_2"
The architecture(s) specified should be among the machine architectures supported by the Debian distribution. These include i386, m68k, sparc, alpha and perhaps others. Architecture-independent packages (e.g. packages having perl or shell script executables, or no executables at all) should specify all as the package architecture.
With this invocation, dchanges will build a changes file named package_name.changes similar to the following:
Date: 01 May 96 22:06 UT Format: 1.3 Source: package Architecture: arch_1 arch_2 Maintainer: name Description: no description provided Priority: Low
The package description should be manually inserted in this changes file, and the completed changes file signed with pgp(1).
At the option of the distribution maintainer, the named maintainer may be registered as an architecture maintainer of package_name.
Registered architecture maintainers are responsible for maintining binary packages for a specific architecture which are derived from the source files for the named package. Architecture maintainers registering for a package which already has a source maintainer are expected to use the source files maintained by the source maintainer. An architecture maintainer registering for a package which does not have a source maintainer will become the source maintainer for that package.
CHANGE OF MAINTAINER
Packages may be transferred by the registered Source or Architecture maintainers to another maintainer by invoking dchanges as follows:
dchanges [options] [arch=name] pkg=package_name \\
maint="new maintainer" pgp="userid"
The userid supplied in this invocation must correspond exactly to the pgp(1) userid for the current package maintainer separately supplied to the distribution maintainer, and will be used to sign the changes file. Because pgp(1) userids normally contain embedded blank chars, the userid assignment should be quoted. With this invocation, dchanges will build a changes file named package_name.changes similar to the following:
Date: 01 May 96 22:06 UT Format: 1.3 Source: package_name Maintainer: new maintainer
If the arch=name override is specified, an Architecture field is included as well.
Prior to doing this, the new maintainer must have provided his pgp userid to the distribution maintainer. Care must be used in specifying the Maintainer field, as it must exactly match the userid associated with the pgp(1) public key for this new package maintainer separately supplied to the distribution maintainer.
At the option of the distribution maintainer, the maintainer named in the changes file may be registered as source and/or architecture maintainer of package_name.
DELETING A PACKAGE, AND OTHER SPECIAL ACTIONS
To delete or orphan a package upload a change of maintainer file with the maintainer set to DELETED or ORPHAN.
OPTIONS
-
-e This option causes the Description field of the changes file to include the full extended description from the binary files as well as the one-line summary description.
-
-n This option suppresses the normal edit of the changes file. It is generally used when running dchanges from a script.
-
-p This option suppresses the normal invocation of pgp(1) to sign the changes file.
-
-? This option causes dchanges to output usage information to stderr.
OVERRIDES
-
cs=string The contents of string is placed in the Changes field summary.
-
ce=file The contents of the named file is placed in the Changes field extension. The file is filtered to prefix each line with a single space character, expand tabs, and coerce blank lines to " .".
-
pri=string The contents of string is placed in the Priority field summary. The string must be a legal changes file priority value.
-
pgp=name The named userid will be used in signing the changes file with pgp(1) , and must correspond exactly with the pgp userid This option should only be used if no binary files are named in the dchanges invocation, as the maintainer userid specified in the first binary file encountered is normally used. Since pgp userids normally contain blank chars, name should be quoted. This override implies the absence of the -p option.
-
sf=file Include the file as a special file. No errors are produced about the file name (although warnings are). The section is set to byhand. This is used for files that need the attention of the distribution maintainer.
-
dist=name The package is intended to be placed in the named distribution(s). Multiple distributions may be named by enclosing a blank delimited list in quotes. If this override is omitted, the package is presumed to be intended for the unstable distribution.
-
sect=name Put the source package files into this section. Also sets the current section (see s= override).
The following are section/priority overrides for .deb files.
-
s=name Set the current section name. p=name Set the current priority.
The following overrides are normally used when no .deb files are being uploaded.
-
arch=name The binary files are targeted for the named architectures(s). Multiple architectures may be named by enclosing a blank delimited list in quotes.
-
src=name The package name specified will be placed in the Package field of the changes file. This override should only be used if no .deb files are named in the dchanges invocation.
-
ver=name The source package version. This is only needed if there are no .deb files named in the dchanges invocation.
-
bin=names Binary package names. This should only be used in there are no .deb files named in the dchanges invocation.
-
maint=name The maintainers name.
DIAGNOSTICS
dchanges exits with a status of 0 on success, and with a nonzero status to indicate an error.
BUGS
Lots probably.
Currently the only way to set sections is to have them in the .deb files and the first one is used for the source files.
SEE ALSO
dchanges(5)
dpkg(1)
pgp(1)
Debian Packaging Guidelines, /usr/doc/Debian/Guidelines