Re: dchanges file for non-intel archs

[Bill Mitchell <mitchell@mdd.comm.mot.com>]

On FriPD, 1 Mar 1996, Juergen Menden wrote:

> [.. questions/concerns about dchanges and non-intel packages ...]

Nice timing.

Working with Bruce Perens, I've put together a new  package
with the intent of addressing this.  A couple of days ago, I sent
a copy to Ian J. for comment.  I don't want to upload it or announce
it to the full debian-devel list until Ian has a chance to comment on
it, but I'll append the draft man page below.  I'll also copy this to
-private.  I had intended to wait for feedback from Ian J.
before doing that but, since you raise the issue, I think it's
probably appropriate to get the current pre-release man page out for at 
least this limited review.

I'm hoping that this is in final form, or close to it, but it's
not yet cast in stone.  Constructive input would be welcome.

.\" Author:  Bill Mitchell
.\"
.\" $Log: dchanges.1,v $
.\"
.TH DCHANGES 1 "Debian Packaging Utilities"
.SH NAME
dchanges \- build changes file for a debian package
.SH SYNOPSIS
.nf
\fBdchanges\fR [options] [overrides] pkgname
\fBdchanges\fR [options] [overrides] filenames
\fBdchanges\fR -?
.fi
.SH DESCRIPTION
\fBdchanges\fR builds the changes file needed to place a package
into the debian distribution, or syntax checks a list of named
changes files.
.LP
Once the changes file is built, the user is normally dropped
into an editor to edit the file and make any needed changes
or corrections to it.
The \fB-n\fR option is provided to suppress this editing operation
if desired.
A syntax check is then performed on the changes file.
.LP
Changes files built by the \fBdchanges\fR 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
.BR dchanges( 5 )
be followed exactly.  The \fBdchanges\fR program is a tool which
aids in properly formatting changes files.
.LP
Once completed, changes files should be signed with the 
.BR pgp( 1 )
program and uploaded along with the package files, if any,
to the debian distribution maintenance site.
Uploaded changes files will have their signatures verified, and
will then be processed according to their contents.
.SH REGISTERING AS A PACKAGE MAINTAINER
.LP
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 maintainer
of that package by invoking \fBdchanges\fR as follows:
.LP
.nf
.B \ \ \ \ dchanges [options] pkg=package_name
.fi
.LP
With this invocation, \fBdchanges\fR will build a changes file named
package_name.changes similar to the following:
.LP
.nf
.B \ \ \ \ Date: Sat Aug 26 12:14:32 PDT 1995
.B \ \ \ \ Format: 1.3
.B \ \ \ \ Source: package_name
.B \ \ \ \ Maintainer:
.B \ \ \ \ Description: no description provided
.B \ \ \ \ Priority: Low
.fi
.LP
The package description should be manually inserted in this changes
file.  The maintainer name and email address should also be manually
inserted, and must correspond with the
.BR pgp( 1 )
public key for this package maintainer separately supplied to the
distribution maintainer.
.LP
Normally, a summary package description placed entirely on the
\fBDescription:\fR 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
.BR 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., " .").
.LP
At the option of the distribution
maintainer, the named maintainer may be registered
as the source maintainer of package_name.
.LP
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.
.SH REGISTERING AS A PACKAGE ARCHITECTURE MAINTAINER
.LP
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 \fBdchanges\fR
as follows:
.LP
.nf
.B \ \ \ \ dchanges [options] pkg=package_name arch=architecture
.fi
.LP
Multiple
architectures may be specified by enclosing the architecture argument
in quotes and providing a blank-delimited list, as follows:
.LP
.nf
.B \ \ \ \ dchanges [options] pkg=source_package_name arch="arch_1 arch_2"
.fi
.LP
The architecture(s) specified should be among the machine
architectures supported by the debian distribution.
These include \fBi386\fR, \fBm68k\fR, \fBsparc\fR, and perhaps others.
Architecture-independent packages (e.g. packages having perl
or shell script executables, or no executables at all) should
specify \fBall\fR as the package architecture.
.LP
With this invocation, \fBdchanges\fR will build a changes file named
package_name.changes similar to the following:
.LP
.nf
.B \ \ \ \ Date: Sat Aug 26 12:14:32 PDT 1995
.B \ \ \ \ Format: 1.3
.B \ \ \ \ Source: package_name
.B \ \ \ \ Architecture: arch_1 arch_2
.B \ \ \ \ Maintainer:
.B \ \ \ \ Description: no description provided
.B \ \ \ \ Priority: Low
.fi
.LP
The package description should be manually inserted in this changes
file, and the completed changes file signed with
.BR pgp( 1 ).
.LP
At the option of the distribution
maintainer, the named maintainer may be registered
as an architecture maintainer of package_name.
If this registration is accepted, and the package currently
has no registered source maintainer, the named maintainer
will be registered as the source maintainer for the package
as well.
.LP
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.
.SH ANNOUNCING UPLOADED PACKAGE FILES
.LP
Maintainers may build a changes file to announce uploaded
package files by invoking \fBdchanges\fR
as follows:
.LP
.B \ \ \ \ dchanges [options] [overrides] file_list
.fi
.LP
If the \fBarch=name\fR override is not specified here, \fBdchanges\fR
will attempt to infer the architecture name(s) from the Architecture
field of any package binary \fB.deb\fR files named.
The architecture name is defaulted to to \fBi386\fR for \fB.deb\fR
files not providing an Architecture field.
Architecture(s) specified should be among the machine
architectures supported by the debian distribution. These 
include \fBi386\fR, \fBm68k\fR, \fBsparc\fR, and perhaps others.
Architecture-independent packages (e.g. packages having perl
or shell script executables, or no executables at all) should
specify \fBall\fR as the package architecture.
.LP
Files in \fBfile_list\fR must all be named using standard debian
package naming conventions, and should have the form:
.nf
.LP
\ \ \ \ \fBpackage_name\fR-\fBpackage_version\fR.\fBextension\fR
.fi
.LP
\fBpackage_name\fR is the name of the package declared by the
Source maintainer.
.LP
\fBpackage_version\fR is the upstream version number and debian
revision number of the package, separated by a \fB-\fR character.
The package_version must contain exactly one \fB-\fR char,
separating the upstream version number from the debian package
revision number.
Any other \fB-\fR chars which may be present in the upstream
version number should be replaced with \fB_\fR or \fB.\fR chars.
The debian revision number is assigned by the package Source
maintainer, and should be incremented with each Source revision.
For packages specific to the debian distribution
or having no upstream maintainer, the debian revision number might
be arbitrarily set to 0 or 1.
.LP
\fBdchanges\fR will infer the source package version from the
first version-numbered file encountered.  This should be a
concern only in rare special cases where some binary package
files have version numbers differing from the version number
of the source package which produces them,
In this case, the \fB-v\fR option must be specified and the
special concerns mentoned in the discussion below of that
option should be observed.
.LP
For the source maintainer, \fBfile_list\fR should include one source
.BR tar( 1 )
archive file having a \fB.tar.gz\fR extension
and one compressed diff file having a \fB.diff.gz\fR 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, a .diff.gz file which contains no diffs
can be produced as follows:
.LP
.nf
.B \ \ \ \ gzip -c </dev/null >pkg-version-revision.diff.gz
.fi
.LP
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.
.LP
For architecture maintainers, \fBfile_list\fR must include at least one binary
package file having a \fB.deb\fR extension per architecture.  Binary
file extensions should specify the architecture name immediately
preceeding the \fB.deb\fR extension, and delimited from it by
a \fB.\fR char (e.g., ed-0.2-5.sparc.diff).
.LP
A changes file produced to upload package files might look
something like the following:
.LP
.nf
.B \ \ \ \ Date: Sat Aug 26 12:14:32 PDT 1995
.B \ \ \ \ Format: 1.3
.B \ \ \ \ Distribution: development
.B \ \ \ \ Source: bc
.B \ \ \ \ Architecture: sparc
.B \ \ \ \ Binary: bc dc
.B \ \ \ \ Version: 1.03-8
.B \ \ \ \ Maintainer: Bill Mitchell <mitchell@mdd.comm.mot.com>
.B \ \ \ \ Description:
.B \ \ \ \ \ bc: An arbitrary precision calculator language.
.B \ \ \ \ \ dc: An arbitrary precision reverse-polish calculator.
.B \ \ \ \ Priority: Routine
.B \ \ \ \ Changes:
.B \ \ \ \ \ This is a Changes field extension.
.B \ \ \ \ \ Each line is indented by a single space character.
.B \ \ \ \ \ .
.B \ \ \ \ \ The line above indicates a blank line.
.B \ \ \ \ Files
.B \ \ \ \ \ bc-1.03-8.diff.gz source 12345 293bb2e6033eeeaf685c03c30baef822
.B \ \ \ \ \ bc-1.03-8.tar.gz source 6789 bcf4ce45101d5fb4a2db0aed3d57df86
.B \ \ \ \ \ bc-1.03-8.sparc.deb editors 12345 a784e82d6a6c684618fd11bb6a4de300
.B \ \ \ \ \ dc-1.03-8.sparc.deb editors 13579 1ac1ed1dff4cfb69a699f5c69fcff179  
.fi
.LP
This changes file may then be signed with
.BR 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 \fBbc\fR 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.
.LP
The changes file format is explained in detail in the
.BR dchanges( 5 )
man page.
The contents of the various fields is determined
by \fBdchanges\fR while building the changes file, using
information gleaned from invocation options and overrides and
from the package files themselves.
.LP
.SH CHANGE OF MAINTAINER
.LP
Packages may be transferred by the registered Source or Architecture
maintainers to another maintainer by invoking \fBdchanges\fR as follows:
.LP
.nf
.B \ \ \ \ dchanges [options] [arch=name] pkg=package_name pgp="userid"
.fi
.LP
The userid supplied in this invocation must correspond exactly to the
.BR pgp( 1 )
userid for the current package maintainer separately supplied to
the distribution maintainer, and will be used to sign the changes
file.
Because
.BR pgp( 1 )
userids normally contain embedded blank chars, the userid assignment
should be quoted.
With this invocation, \fBdchanges\fR will build a changes file named
package_name.changes similar to the following:
.LP
.nf
.B \ \ \ \ Date: Sat Aug 26 12:14:32 PDT 1995
.B \ \ \ \ Format: 1.3
.B \ \ \ \ Source: package_name
.B \ \ \ \ Maintainer:
.fi
.B Priority: Low
.fi
.LP
If the \fBarch=name\fR override is specified, an \fBArchitecture\fR
field is included as well.
.LP
The proper maintainer name and email address of the new maintainer
should be manually inserted in this changes file as follows:
.LP
.nf
.B \ \ \ \ Maintainer: John Doe <jdoe@somehost.somedomain>
.fi
.LP
Prior to doing this, the new maintainer must have provided his
pgp userid to the distribution maintainer.  Care must be used
in specifying the \fBMaintainer\fR field, as it must exactly
match the userid associated with the
.BR pgp( 1 )
public key for this new package maintainer separately supplied to
the distribution maintainer.
.LP
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.
.SH DELETING A PACKAGE, AND OTHER SPECIAL ACTIONS
.LP
Special actions such as deleting a package or declaring it
an orphan (an orphan package is a package with no maintainer)
may be accomplished by invoking \fBdchanges\fR as follows:
.LP
.nf
.B \ \ \ \ dchanges [options] [arch=arch_name] pkg=package_name
.fi
.LP
With this invocation, \fBdchanges\fR will build a changes file named
package_name.changes similar to the following:
.LP
.nf
.B \ \ \ \ Date: Sat Aug 26 12:14:32 PDT 1995
.B \ \ \ \ Format: 1.3
.B \ \ \ \ Source: package_name
.B \ \ \ \ Architecture: arch_name
.B \ \ \ \ Maintainer:
.B \ \ \ \ Description: no description provided
.B \ \ \ \ Priority: Low
.fi
.LP
The proper maintainer name and email address should be manually
inserted in this changes file, and a \fBMessage\fR field manually added.
Care should be exercised to assure that the \fBMessage\fR field
added conforms to the changes file format described in
.BR dchanges( 5 ) .
In particular, the body lines in the message should be indented
by a single blank char, and blank lines in the message body
should be indicated by a line containing only a single blank char
followed by a perion (" .").  An example message asking that a
package be declared orphan might look something like the following:
.LP
.nf
.B \ \ \ \ Message:
.B \ \ \ \ \ Due to the press of other work, I am afraid that I will
.B \ \ \ \ \ be unable to continue to maintain this package.  I have
.B \ \ \ \ \ not been able to identify a replacement maintainer to
.B \ \ \ \ \ take over as package maintainer.  Please declare this
.B \ \ \ \ \ package orphan.
.fi
.SH OPTIONS
.IP
.I "\-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.
.IP
.I "\-n
This option suppresses the normal edit of the changes file.
It is generally used when running \fBdchanges\fR from a script.
.IP
.I "\-p
This option suppresses the normal invocation of pgp(1) to sign the
changes file
.IP
.I "\-s
This option causes \fBdchanges\fR to perform a changes file syntax
check on the files named in the remaindier of the command line.
.IP
.I "\-v
This option causes \fBdchanges\fR suppress the normal check that
all files have the same package version number.
This option should only be used in the rare case where some
binary packages generated by a source package have version
numbers which differ from the version number of the source
package which produces them.
In this case, either a file with the same version number as
the source package version number (e.g., the .tar.gz file, if that
file is included in the file list), should be specified on the
invocation command line prior to the binary file(s) with the
differing version number(s) or, alternatively, the \fBver=version\fR
override should be used to explicitly specify the source package
version number.
.IP
.I "\-?
This option causes \fBdchanges\fR to output usage information to stderr.
.SH OVERRIDES
.IP
.I "cs=string
The contents of string is placed in the \fBChanges\fR field summary.
.IP
.I "ce=file
The contents of the named file is placed in the \fBChanges\fR field
extension.
The file is filtered to prefix each line with a single space
character, expand tabs, and coerce blank lines to " .".
.IP
.I "ps=string
The contents of string is placed in the \fBPriority\fR field summary.
The string must be a legal changes file priority value.
.IP
.I "pe=file
The contents of the named file is placed in the \fBPriority\fR field
extension.
The file is filtered to prefix each line with a single space
character, expand tabs, and coerce blank lines to " .".
.IP
.I "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 \fBdevelopment\fR distribution.
.IP
.I 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.
.IP
.I force=name
This forces \fBdchanges\fR to provide only \fBDate\fR,
\fBFormat\fR, and \fBFiles\fR fields by internal processing.
The remaining fields are inserted literally following the
\fBFormat\fR field from the file named.
It is the maintainer's responsibility to assure that all required
fields are provided, and that the fields provided are in the proper
format.
This override is expected to be used only in rare special cases.
.IP
.I pkg=name
The package name specified will be placed in the \fBPackage\fR
field of the changes file.
This override should only be used if no package files are
named in the \fBdchanges\fR invocation.
.IP
.I pgp=name
The named userid will be used in signing the changes file with
.BR pgp( 1 )
, and must correspond exactly with the pgp userid 
This option should only be used if no binary files are named in
the \fBdchanges\fR invocation, as the maintainer userid specified
in the first binary file encountered is normally used.
Since pgp userids normally contain blank chars, \fBname\fR
should be quoted.  This override implies the absence of the \fB-p\fR option.
.IP
.I ver=string
The string specified will be used as the package version number.
.SH SEE ALSO
.BR dchanges( 5 )
.br
.BR dpkg( 1 )
.br
.BR pgp( 1 )
.nf
\fIDebian Packaging Guidelines\fR, /usr/doc/Debian/Guidelines
.fi