summaryrefslogtreecommitdiffstats
path: root/scripts/debchange.1
diff options
context:
space:
mode:
Diffstat (limited to 'scripts/debchange.1')
-rw-r--r--scripts/debchange.1490
1 files changed, 490 insertions, 0 deletions
diff --git a/scripts/debchange.1 b/scripts/debchange.1
new file mode 100644
index 0000000..95c73f4
--- /dev/null
+++ b/scripts/debchange.1
@@ -0,0 +1,490 @@
+.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 the text given on the command line is a null string,
+\fBdebchange\fR will run in batch mode without adding any text. If the
+text given on the command line is a space string, \fBdebchange\fR will run
+in batch mode and add a blank changelog entry.
+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 \fIchangelog\fR or \fINEWS\fR
+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
+https://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
+\fIchangelog\fR heuristic assumes the package has been released unless its
+changelog contains \fBUNRELEASED\fR in the distribution field. If this heuristic
+is enabled then the distribution will default to \fBUNRELEASED\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. The alternate
+\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.
+.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\-\-\fR[\fBno\fR]\fBmultimaint\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
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and
+their corresponding command-line options \fB\-\-check-dirname-level\fR
+and \fB\-\-check-dirname-regex\fR.
+.PP
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR 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 \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR 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 '\fB/\fR',
+then it must match the full directory path. If not, then it must
+match the full directory name. If \fIregex\fR contains the string
+\'\fBPACKAGE\fR', this will be replaced by the source package name, as
+determined from the changelog. The default value for the regex is:
+\'\fBPACKAGE(-.+)?\fR', thus matching directory names such as \fBPACKAGE\fR and
+\fBPACKAGE-\fIversion\fR.
+.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 \fBCHANGELOG\fR 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. On Ubuntu or Tanglu,
+this will also change the suffix from buildX to ubuntu1/tanglu1. Use
+\fB\-R\fR, \fB\-\-rebuild\fR for a no change rebuild increment. 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.
+If \fBDEBCHANGE_RELEASE_HEURISTIC\fR is \fIchangelog\fR (default) and the
+current release is \fIUNRELEASED\fR, this will only change the version of the
+current changelog stanza. Otherwise, this will create a new changelog stanza
+with the new version.
+.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.
+If \fBDEBCHANGE_RELEASE_HEURISTIC\fR is \fIchangelog\fR (default) and the
+current release is \fIUNRELEASED\fR, this will only change the version of the
+current changelog stanza. Otherwise, this will create a new changelog stanza
+with the new version.
+.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
+\fBUNRELEASED\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, \fBunstable\fR will be used.
+.TP
+.BR \-\-force\-save\-on\-release
+When \fB\-\-release\fR is used, an editor is opened to allow inspection
+of the changelog. The user is required to save the file to accept the modified
+changelog, otherwise the original will be kept (default).
+.TP
+.BR \-\-no\-force\-save\-on\-release
+Do not do so. Note that a dummy changelog entry may 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 \fIchangelog\fR 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 \fIchangelog\fR file.
+.TP
+.BR \-\-empty
+When used in combination with \fB\-\-create\fR, suppress the automatic
+addition of an "\fBinitial release\fR" 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 "\fB.1\fR" to a non-NMU version number (unless the package
+is Debian native, in which case "\fB+nmu1\fR" 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 \fBMaintainer\fR nor the \fBUploaders\fR
+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 "\fB+b1\fR" 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 \fBQA upload\fR changelog comment.
+.TP
+.BR \-\-rebuild ", " \-R
+Increment the Debian release number for a no-change rebuild by
+appending a "build1" or by incrementing a rebuild version number.
+.TP
+.BR \-\-security ", " \-s
+Increment the Debian release number for a Debian Security Team non-maintainer
+upload, and add a \fBSecurity Team upload\fR changelog comment.
+.TP
+.BR \-\-lts
+Increment the Debian release number for a LTS Security Team non-maintainer
+upload, and add a \fBLTS Security Team upload\fR changelog comment.
+.TP
+.B \-\-team
+Increment the Debian release number for a team upload, and add a \fBTeam upload\fR
+changelog comment.
+.TP
+.BR \-\-upstream ", " \-U
+Don't append \fBdistro-name1\fR to the version on a derived
+distribution. Increment the Debian version.
+.TP
+.B \-\-bpo
+Increment the Debian release number for an upload to buster-backports,
+and add a backport upload changelog comment.
+.TP
+.B \-\-stable
+Increment the Debian release number for an upload to the current stable
+release.
+.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
+.B \-\-allow\-lower\-version \fIpattern\fR
+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\fB-\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\fB-1\fR (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\fR[\fB,\fInnnnn \fR...]
+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 \-\-\fR[\fBno\fR]\fBquery
+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\-\-vendor \fIvendor\fR
+Override the distributor ID over the default returned by dpkg-vendor.
+This name is used for heuristics applied to new package versions and for
+sanity checking of the target distribution.
+.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 "\fBmedium\fR" 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 \fBCHANGELOG\fR
+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\-\-\fR[\fBno\fR]\fBmultimaint\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\-\-\fR[\fBno\fR]\fBmultimaint\-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 \-\-controlmaint ", " \-M
+Use maintainer details from the \fIdebian/control\fR \fBMaintainer\fR field
+rather than relevant environment variables (\fBDEBFULLNAME\fR, \fBDEBEMAIL\fR,
+etc.). This option might be useful to restore details of the main maintainer
+in the changelog trailer after a bogus edit (e.g. when \fB\-m\fR was intended
+but forgot) or when releasing a package in the name of the main maintainer
+(e.g. the team).
+.TP
+.BR \-\-\fR[\fBno\fR]\fBmainttrailer ", " \-t
+If \fBmainttrailer\fR 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 "\fBDirectory name checking\fR" for an explanation of
+this option.
+.TP
+\fB\-\-check-dirname-regex\fR \fIregex\fR
+See the above section "\fBDirectory name checking\fR" 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\fR|\fIchangelog\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 "\fBDirectory name checking\fR" 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 `\fBdate \-R\fR` and affected by the environment variable \fBTZ\fR.
+.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.
+.TP
+.B DEBCHANGE_VENDOR
+Use this vendor instead of the default (dpkg-vendor output). See
+\fB\-\-vendor\fR for details.
+.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 debc (1),
+.BR debclean (1),
+.BR dput (1),
+.BR dupload (1),
+.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>.