--- name: "dchanges" section: "1" platform: "linux" package: "dchanges" version: "3.3" release: "Debian 1.1 (Buzz)" platforms: ["linux"] url: "https://new.carta.tech/dchanges" --- # dchanges(1) build changes file for a Debian package ## 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: \ \[\\]** If there is no **Source** field in the **.deb** file then the \ and version are assumed to be the binary package name and version. If the \ 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=\** and **p=\** 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 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 " ``` 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 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 ```