diff options
Diffstat (limited to '')
| -rw-r--r-- | scripts/debchange.1 | 491 |
1 files changed, 491 insertions, 0 deletions
diff --git a/scripts/debchange.1 b/scripts/debchange.1 new file mode 100644 index 0000000..d1f02de --- /dev/null +++ b/scripts/debchange.1 @@ -0,0 +1,491 @@ +.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 (or the name of the current development +release when run under Ubuntu). +.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 bullseye-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>. |