devscripts (2.10.69+squeeze4) stable-security; urgency=high

[devscripts.git] / scripts / debchange.1

.TH DEBCHANGE 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
.SH NAME
debchange \- Tool for maintenance of the debian/changelog file in a source package
.SH SYNOPSIS
\fBdebchange\fR [\fIoptions\fR] [\fItext\fR ...]
.br
\fBdch\fR [\fIoptions\fR] [\fItext\fR ...]
.SH DESCRIPTION
\fBdebchange\fR or its alias \fBdch\fR will add a new comment line to
the Debian changelog in the current source tree.  This command must be
run from within that tree.  If the text of the change is given on the
command line, \fBdebchange\fR will run in batch mode and simply add the
text, with line breaks as necessary, at the appropriate place in
\fIdebian/changelog\fR (or the changelog specified by options, as
described below).  If no text is specified then \fBdebchange\fR
will run the editor as determined by \fBsensible-editor\fR for you to
edit the file.  (The environment variables \fBVISUAL\fR and
\fBEDITOR\fR are used in this order to determine which editor to use.)
Editors which understand the \fI+n\fR option for starting the editing
on a specified line will use this to move to the correct line of the
file for editing.  If the editor is quit without modifying the
temporary file, \fBdebchange\fR will exit without touching the
existing changelog.  \fBNote that the changelog is assumed to be
encoded with the UTF-8 encoding.  If it is not, problems may occur.\fR
Please see the \fBiconv\fR(1) manpage to find out how to convert
changelogs from legacy encodings.  Finally, a changelog or NEWS
file can be created from scratch using the \fB\-\-create\fR option
described below.
.PP
\fBdebchange\fR also supports automatically producing bug-closing
changelog entries, using the \fB\-\-closes\fR option.  This will
usually query the BTS, the Debian Bug Tracking System (see
http://bugs.debian.org/) to determine the title of the bug and the
package in which it occurs.  This behaviour can be stopped by giving a
\fB\-\-noquery\fR option or by setting the configuration variable
\fBDEBCHANGE_QUERY_BTS\fR to \fIno\fR, as described below.  In either
case, the editor (as described above) will always be invoked to give
an opportunity to modify the entries, and the changelog will be
accepted whether or not modifications are made.  An extra changelog
entry can be given on the command line in addition to the closes
entries.
.PP
At most one of \fB\-\-append\fR, \fB\-\-increment\fR, \fB\-\-edit\fR,
\fB\-\-release\fR, and \fB\-\-newversion\fR may be specified as listed
below. If no options are specified, \fBdebchange\fR will use heuristics to
guess whether or not the package has been successfully released, and behave
as if \fB\-\-increment\fR had been specified if the package has been
released, or otherwise as if \fB\-\-append\fR has been specified.
.PP
Two different sets of heuristics can be used, as controlled by the
\fB\-\-release-heuristic\fR option or the
\fBDEBCHANGE_RELEASE_HEURISTIC\fR configuration variable. The default
\fIlog\fR heuristic determines if a package has been released by looking for an
appropriate \fBdupload\fR(1) or \fBdput\fR(1) log file in the parent
directory. A warning will be issued if the log file is found but a
successful upload is not recorded. This may be because the previous upload
was performed with a version of \fBdupload\fR prior to 2.1 or because the
upload failed. The alternate \fIchangelog\fR heuristic assumes the package has
been released unless its changelog contains \fIUNRELEASED\fR in the
distribution field. If this heuristic is enabled then the distribution will
default to \fIUNRELEASED\fR in new changelog entries, and the
\fB\-\-mainttrailer\fR option described below will be automatically
enabled. This can be useful if a package can be released by different
maintainers, or if you do not keep the upload logs.
.PP
If either \fB\-\-increment\fR or \fB\-\-newversion\fR is used, the
name and email for the new version will be determined as follows.  If
the environment variable \fBDEBFULLNAME\fR is set, this will be used
for the maintainer full name; if not, then \fBNAME\fR will be checked.
If the environment variable \fBDEBEMAIL\fR is set, this will be used
for the email address.  If this variable has the form "name <email>",
then the maintainer name will also be taken from here if neither
\fBDEBFULLNAME\fR nor \fBNAME\fR is set.  If this variable is not set,
the same test is performed on the environment variable \fBEMAIL\fR.
Next, if the full name has still not been determined, then use
\fBgetpwuid\fR(3) to determine the name from the password file.  If
this fails, use the previous changelog entry.  For the email address,
if it has not been set from \fBDEBEMAIL\fR or \fBEMAIL\fR, then look
in \fI/etc/mailname\fR, then attempt to build it from the username and
FQDN, otherwise use the email address in the previous changelog entry.
In other words, it's a good idea to set \fBDEBEMAIL\fR and
\fBDEBFULLNAME\fR when using this script.
.PP
Support is included for changelogs that record changes by multiple
co-maintainers of a package. If an entry is appended to the current
version's entries, and the maintainer is different from the maintainer who
is listed as having done the previous entries, then lines will be added to
the changelog to tell which maintainers made which changes. Currently only
one of the several such styles of recording this information is supported,
in which the name of the maintainer who made a set of changes appears
on a line before the changes, inside square brackets. This can be
switched on and off using the \fB\-\-[no]multimaint\fR option or the
\fBDEBCHANGE_MULTIMAINT\fR configuration file option; the default is to
enable it.  Note that if an entry has already been marked in this way,
then this option will be silently ignored.
.PP
If the directory name of the source tree has the form
\fIpackage\fR-\fIversion\fR, then \fBdebchange\fR will also attempt to
rename it if the (upstream) version number changes.  This can be
prevented by using the \fB\-\-preserve\fR command line or
configuration file option as described below.
.PP
If \fB\-\-force\-bad\-version\fR or \fB\-\-allow\-lower\-version\fR is used,
\fBdebchange\fR will not stop if the new version is less than the current one.
This is especially useful while doing backports. 
.SH "Directory name checking"
In common with several other scripts in the \fBdevscripts\fR package,
\fBdebchange\fR will climb the directory tree until it finds a
\fIdebian/changelog\fR file.  As a safeguard against stray files
causing potential problems, it will examine the name of the parent
directory once it finds the \fIdebian/changelog\fR file, and check
that the directory name corresponds to the package name.  Precisely
how it does this is controlled by two configuration file variables
DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and
their corresponding command-line options \fB\-\-check-dirname-level\fR
and \fB\-\-check-dirname-regex\fR.
.PP
DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
.TP
.B 0
Never check the directory name.
.TP
.B 1
Only check the directory name if we have had to change directory in
our search for \fIdebian/changelog\fR.  This is the default behaviour.
.TP
.B 2
Always check the directory name.
.PP
The directory name is checked by testing whether the current directory
name (as determined by \fBpwd\fR(1)) matches the regex given by the
configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
command line option \fB\-\-check-dirname-regex\fR \fIregex\fR.  Here
\fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be
anchored at the beginning and the end.  If \fIregex\fR contains a '/',
then it must match the full directory path.  If not, then it must
match the full directory name.  If \fIregex\fR contains the string
\'PACKAGE', this will be replaced by the source package name, as
determined from the changelog.  The default value for the regex is:
\'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and
PACKAGE-version.
.PP
The default changelog to be edited is \fIdebian/changelog\fR; however,
this can be changed using the \fB\-\-changelog\fR or \fB\-\-news\fR
options or the CHANGELOG environment variable, as described below.
.SH OPTIONS
.TP
.BR \-\-append ", " \-a
Add a new changelog entry at the end of the current version's entries.
.TP
.BR \-\-increment ", " \-i
Increment either the final component of the Debian release number or,
if this is a native Debian package, the version number.  This creates
a new section at the beginning of the changelog with appropriate
headers and footers.  Also, if this is a new version of a native
Debian package, the directory name is changed to reflect this.
.TP
\fB\-\-newversion \fIversion\fR, \fB\-v \fIversion\fR
This specifies the version number (including the Debian release part)
explicitly and behaves as the \fB\-\-increment\fR option in other
respects.  It will also change the directory name if the upstream
version number has changed.
.TP
.BR \-\-edit ", " \-e
Edit the changelog in an editor.
.TP
.BR \-\-release ", " \-r
Finalize the changelog for a release.
Update the changelog timestamp. If the distribution is set to
\fIUNRELEASED\fR, change it to the distribution from the previous changelog entry 
(or another distribution as specified by \fB\-\-distribution\fR).  If there are 
no previous changelog entries and an explicit distribution has not been 
specified, \fIunstable\fR will be used.
.TP
.BR \-\-force\-save\-on\-release
When \-\-release is used and an editor opened to allow inspection
of the changelog, require the user to save the changelog their editor opened.
Otherwise, the original changelog will not be modified. (default)
.TP
.BR \-\-no\-force\-save\-on\-release
Do not do so. Note that a dummy changelog entry made be supplied
in order to achieve the same effect - e.g. \fBdebchange \-\-release ""\fR.
The entry will not be added to the changelog but its presence will suppress
the editor.
.TP
.BR \-\-create
This will create a new \fIdebian/changelog\fR file (or \fINEWS\fR if
the \fB\-\-news\fR option is used).  You must be in the top-level
directory to use this; no directory name checking will be performed.
The package name and version can either be specified using the
\fB\-\-package\fR and \fB\-\-newversion\fR options, determined from
the directory name using the \fB\-\-fromdirname\fR option or entered
manually into the generated changelog file.  The maintainer name is
determined from the environment if this is possible, and the
distribution is specified either using the \fB\-\-distribution\fR
option or in the generated changelog file.
.TP
.BR \-\-empty
When used in combination with \fB\-\-create\fR, suppress the automatic
addition of an "initial release" changelog entry (so that the next
invocation of \fBdebchange\fR adds the first entry).  Note that this
will cause a \fBdpkg\-parsechangelog\fR warning on the next invocation
due to the lack of changes.
.TP
\fB\-\-package\fR \fIpackage\fR
This specifies the package name to be used in the new changelog; this
may only be used in conjunction with the \fB\-\-create\fR, \fB\-\-increment\fR and
\fB\-\-newversion\fR options.
.TP
.BR \-\-nmu ", " \-n
Increment the Debian release number for a non-maintainer upload by
either appending a ".1" to a non-NMU version number (unless the package
is Debian native, in which case "+nmu1" is appended) or by incrementing
an NMU version number, and add an NMU changelog comment.  This happens
automatically if the packager is neither in the Maintainer nor the Uploaders
field in \fIdebian/control\fR, unless \fBDEBCHANGE_AUTO_NMU\fR is set to
\fIno\fR or the \fB\-\-no\-auto\-nmu\fR option is used.
.TP
.BR \-\-bin\-nmu
Increment the Debian release number for a binary non-maintainer upload
by either appending a "+b1" to a non-binNMU version number or by
incrementing a binNMU version number, and add a binNMU changelog comment.
.TP
.BR \-\-qa ", " \-q
Increment the Debian release number for a Debian QA Team upload, and
add a QA upload changelog comment.
.TP
.BR \-\-security ", " \-s
Increment the Debian release number for a Debian Security Team non-maintainer
upload, and add a Security Team upload changelog comment.
.TP
.B \-\-team
Increment the Debian release number for a team upload, and add a team upload
changelog comment.
.TP
.B \-\-bpo
Increment the Debian release number for an upload to lenny-backports,
and add a backport upload changelog comment.
.TP
.BR \-\-local ", " \-l \fIsuffix\fR
 Add a suffix to the Debian version number for a local build.
.TP
.BR \-\-force\-bad\-version ", " \-b
Force a version number to be less than the current one (e.g., when
backporting).
.TP
.BR \-\-allow\-lower\-version
Allow a version number to be less than the current one if the new version
matches the specified pattern.
.TP
.BR \-\-force\-distribution
Force the provided distribution to be used, even if it doesn't match the list of known 
distributions (e.g. for unofficial distributions).
.TP
.BR \-\-auto\-nmu
Attempt to automatically determine whether a change to the changelog
represents a Non Maintainer Upload.  This is the default.
.TP
.BR \-\-no\-auto\-nmu
Disable automatic NMU detection.  Equivalent to setting
\fBDEBCHANGE_AUTO_NMU\fR to \fIno\fR.
.TP
.BR \-\-fromdirname ", " \-d
This will take the upstream version number from the directory name,
which should be of the form \fIpackage\fR-\fIversion\fR.  If the
upstream version number has increased from the most recent changelog
entry, then a new entry will be made with version number
\fIversion\fR-1 (or \fIversion\fR if the package is Debian native),
with the same epoch as the previous package version.  If the upstream
version number is the same, this option will behave in the same way as
\fB\-i\fR.
.TP
.BI \-\-closes " nnnnn,[nnnnn,...]"
Add changelog entries to close the specified bug numbers.  Also invoke
the editor after adding these entries.  Will generate warnings if the
BTS cannot be contacted (and \fB\-\-noquery\fR has not been
specified), or if there are problems with the bug report located.
.TP
.B \-\-[no]query
Should we attempt to query the BTS when generating closes entries?
.TP
.BR \-\-preserve ", " \-p
Preserve the source tree directory name if the upstream version number
(or the version number of a Debian native package) changes.  See also
the configuration variables section below.
.TP
\fB \-\-no\-preserve\fR, \fB\-\-nopreserve\fR
Do not preserve the source tree directory name (default).
.TP
\fB\-\-distribution \fIdist\fR, \fB\-D \fIdist\fR
Use the specified distribution in the changelog entry being edited,
instead of using the previous changelog entry's distribution for new
entries or the existing value for existing entries.
.TP
\fB\-\-urgency \fIurgency\fR, \fB\-u \fIurgency\fR
Use the specified urgency in the changelog entry being edited,
instead of using the default "low" for new entries or the existing
value for existing entries.
.TP
\fB\-\-changelog \fIfile\fR, \fB\-c \fIfile\fR
This will edit the changelog \fIfile\fR instead of the standard
\fIdebian/changelog\fR.  This option overrides any CHANGELOG
environment variable setting.  Also, no directory traversing or
checking will be performed when this option is used.
.TP
\fB\-\-news\fR [\fInewsfile\fR]
This will edit \fInewsfile\fR (by default, \fIdebian/NEWS\fR) instead
of the regular changelog.  Directory searching will be performed.
The changelog will be examined in order to determine the current package 
version.
.TP
\fB\-\-[no]multimaint\fR
Should we indicate that parts of a changelog entry have been made by
different maintainers?  Default is yes; see the discussion above and
also the \fBDEBCHANGE_MULTIMAINT\fR configuration file option below.
.TP
\fB\-\-[no]multimaint\-merge\fR
Should all changes made by the same author be merged into the same
changelog section?  Default is no; see the discussion above and also the
\fBDEBCHANGE_MULTIMAINT_MERGE\fR configuration file option below.
.TP
.BR \-\-maintmaint ", " \-m
Do not modify the maintainer details previously listed in the changelog. 
This is useful particularly for sponsors wanting to automatically add a
sponsorship message without disrupting the other changelog details.
Note that there may be some interesting interactions if
multi-maintainer mode is in use; you will probably wish to check the
changelog manually before uploading it in such cases.
.TP
.BR \-\-[no]mainttrailer ", " \-t
If mainttrailer is set, it will avoid modifying the existing changelog
trailer line (i.e. the maintainer and date-stamp details), unless
used with options that require the trailer to be modified
(e.g. \fB\-\-create\fR, \fB\-\-release\fR, \fB\-i\fR, \fB\-\-qa\fR, etc.)
This option differs from \fB\-\-maintmaint\fR in that it will use
multi-maintainer mode if appropriate, with the exception of editing the
trailer. See also the \fBDEBCHANGE_MAINTTRAILER\fR configuration file option 
below.
.TP
\fB\-\-check-dirname-level\fR \fIN\fR
See the above section "Directory name checking" for an explanation of
this option.
.TP
\fB\-\-check-dirname-regex\fR \fIregex\fR
See the above section "Directory name checking" for an explanation of
this option.
.TP
\fB\-\-no-conf\fR, \fB\-\-noconf\fR
Do not read any configuration files.  This can only be used as the
first option given on the command-line.
.TP
\fB\-\-release\-heuristic\fR \fIlog|changelog\fR
Controls how \fBdebchange\fR determines if a package has been released,
when deciding whether to create a new changelog entry or append to an
existing changelog entry.
.TP
.BR \-\-help ", " \-h
Display a help message and exit successfully.
.TP
.B \-\-version
Display version and copyright information and exit successfully.
.SH "CONFIGURATION VARIABLES"
The two configuration files \fI/etc/devscripts.conf\fR and
\fI~/.devscripts\fR are sourced in that order to set configuration
variables.  Command line options can be used to override configuration
file settings.  Environment variable settings are ignored for this
purpose.  The currently recognised variables are:
.TP
.B DEBCHANGE_PRESERVE
If this is set to \fIyes\fR, then it is the same as the
\fB\-\-preserve\fR command line parameter being used.
.TP
.B DEBCHANGE_QUERY_BTS
If this is set to \fIno\fR, then it is the same as the
\fB\-\-noquery\fR command line parameter being used.
.TP
.BR DEVSCRIPTS_CHECK_DIRNAME_LEVEL ", " DEVSCRIPTS_CHECK_DIRNAME_REGEX
See the above section "Directory name checking" for an explanation of
these variables.  Note that these are package-wide configuration
variables, and will therefore affect all \fBdevscripts\fR scripts
which check their value, as described in their respective manpages and
in \fBdevscripts.conf\fR(5).
.TP
.BR DEBCHANGE_RELEASE_HEURISTIC
Controls how \fBdebchange\fR determines if a package has been released,
when deciding whether to create a new changelog entry or append to an
existing changelog entry. Can be either \fIlog\fR or \fIchangelog\fR.
.TP
.BR DEBCHANGE_MULTIMAINT
If set to \fIno\fR, \fBdebchange\fR will not introduce multiple-maintainer
distinctions when a different maintainer appends an entry to an
existing changelog.  See the discussion above.  Default is \fIyes\fR.
.TP
.BR DEBCHANGE_MULTIMAINT_MERGE
If set to \fIyes\fR, when adding changes in multiple-maintainer mode
\fBdebchange\fR will check whether previous changes by the current
maintainer exist and add the new changes to the existing block
rather than creating a new block.  Default is \fIno\fR.
.TP
.BR DEBCHANGE_MAINTTRAILER
If this is set to \fIno\fR, then it is the same as the
\fB\-\-nomainttrailer\fR command line parameter being used.
.TP
.BR DEBCHANGE_TZ
Use this timezone for changelog entries.  Default is the user/system
timezone as shown by `date \-R` and affected by the environment variable TZ.
.TP
.BR DEBCHANGE_LOWER_VERSION_PATTERN
If this is set, then it is the same as the
\fB\-\-allow\-lower\-version\fR command line parameter being used.
.TP
.BR DEBCHANGE_AUTO_NMU
If this is set to \fIno\fR then \fBdebchange\fR will not attempt to
automatically determine whether the current changelog stanza represents
an NMU.  The default is \fIyes\fR.  See the discussion of the
\fB\-\-nmu\fR option above.
.TP
.BR DEBCHANGE_FORCE_SAVE_ON_RELEASE
If this is set to \fIno\fR, then it is the same as the
\fB\-\-no\-force\-save\-on\-release\fR command line parameter being used.
.SH ENVIRONMENT
.TP
.BR DEBEMAIL ", " EMAIL ", " DEBFULLNAME ", " NAME
See the above description of the use of these environment variables.
.TP
.B CHANGELOG
This variable specifies the changelog to edit in place of
\fIdebian/changelog\fR.  No directory traversal or checking is
performed when this variable is set.  This variable is overridden by
the \fB\-\-changelog\fR command-line setting.
.TP
.BR VISUAL ", " EDITOR
These environment variables (in this order) determine the editor used
by \fBsensible-editor\fR.
.SH "SEE ALSO"
.BR debclean (1),
.BR dupload (1),
.BR dput (1),
.BR debc (1)
and
.BR devscripts.conf (5).
.SH AUTHOR
The original author was Christoph Lameter <clameter@debian.org>. 
Many substantial changes and improvements were made by Julian Gilbey
<jdg@debian.org>.