Here is "patch" for the problem. Also demonstration how the *.pod format
can help the manual page maintenance management.
Notes:
- Formatting have been tried to kept as in original.
- Underline codes in the original have been substituted with I<>,
italics code in POD. Perl does not have underline tag.
- Excessibe bolding of word "debchnage" have been reduced
to minimum (distracts reading).
This manual page was converted from devscripts SVN repository:
SVN r1981 as of 2009-08-31
scripts/debchange.1
To make manual page:
LC_ALL= LANG=C pod2man \
--utf8 \
--center="Debian" \
--name="debchange" \
--section="1" \
debchange.pod |
sed 's,[Pp]erl v[0-9.]\+,debchange,'
Jari
# This is manual page in Perl POD format. Read more at
# http://perldoc.perl.org/perlpod.html or run command:
#
# perldoc perlpod | less
#
# To check the syntax:
#
# podchecker *.pod
#
# Create manual page with command:
#
# pod2man PAGE.N.pod > PAGE.N
=pod
=head1 NAME
debchange Tool for maintenance of the debian/changelog file in a source package
=head1 SYNOPSIS
debchange [options] [text ...]
dch [options] [text ...]
=head1 DESCRIPTION
B<debchange> or its alias B<dch> 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, debchange will run in batch mode and simply add the
text, with line breaks as necessary, at the appropriate place in
debian/changelog (or the changelog specified by options, as described
below). If no text is specified then debchange will run the editor as
determined by L<sensible-editor(1)> for you to edit the file. (The
environment variables C<VISUAL> and C<EDITOR> are used in this order
to determine which editor to use.) Editors which understand the B<+n>
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, debchange will exit without
touching the existing changelog. B<Note that the changelog is assumed
to be encoded with the UTF-8 encoding. If it is not, problems may
occur>. Please see the L<iconv(1)> manpage to find out how to convert
changelogs from legacy encodings. Finally, a F<changelog> or F<NEWS>
file can be created from scratch using the B<--create> option
described below.
debchange also supports automatically producing bug-closing changelog
entries, using the B<--closes> 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 B<--noquery> option or by
setting the configuration variable C<DEBCHANGE_QUERY_BTS> to I<no>, 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.
At most one of B<--append>, B<--increment>, B<--edit>, B<--release>,
and B<--newversion> may be specified as listed below. If no options
are specified, debchange will use heuristics to guess whether or not
the package has been successfully released, and behave as if
B<--increment> had been specified if the package has been released, or
otherwise as if B<--append> has been specified.
Two different sets of heuristics can be used, as controlled by the
B<--release-heuristic> option or the C<DEBCHANGE_RELEASE_HEURISTIC>
configuration variable. The default I<log> heuristic determines if a
package has been released by looking for an appropriate dupload(1) or
L<dput(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
dupload prior to 2.1 or because the upload failed. The alternate
I<changelog> heuristic assumes the package has been released unless its
changelog contains I<UNRELEASED> in the distribution field. If this
heuristic is enabled then the distribution will default to
I<UNRELEASED> in new changelog entries, and the B<--mainttrailer>
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.
If either B<--increment> or B<--newversion> is used, the name and
email for the new version will be determined as follows. If the
environment variable C<DEBFULLNAME> is set, this will be used for the
maintainer full name; if not, then NAME will be checked. If the
environment variable C<DEBEMAIL> 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 C<DEBFULLNAME>
nor C<NAME> is set. If this variable is not set, the same test is
performed on the environment variable C<EMAIL>. Next, if the full name
has still not been determined, then use L<getpwuid(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
C<DEBEMAIL> or C<EMAIL>, then look in F</etc/mailname>, 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 C<DEBEMAIL> and C<DEBFULLNAME> when using this script.
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
B<--[no]multimaint> option or the C<DEBCHANGE_MULTIMAINT>
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.
If the directory name of the source tree has the form
I<package-version>, then debchange will also attempt to rename it if
the (upstream) version number changes. This can be prevented by using
the B<--preserve> command line or configuration file option as
described below.
If B<--force-bad-version> or B<--allow-lower-version> is used,
debchange will not stop if the new version is less than the current
one. This is especially useful while doing backports.
=head2 Directory name checking
In common with several other scripts in the B<devscripts> package,
debchange will climb the directory tree until it finds a
F<debian/changelog> file. As a safeguard against stray files causing
potential problems, it will examine the name of the parent directory
once it finds the debian/changelog file, and check that the directory
name corresponds to the package name. Precisely how it does this is
controlled by two configuration file variables
C<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> and
C<DEVSCRIPTS_CHECK_DIRNAME_REGEX>, and their corresponding
command-line options B<--check-dirname-level> and
B<--check-dirname-regex>.
C<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> can take the following values:
=over 4
=item B<0>
Never check the directory name.
=item B<1>
Only check the directory name if we have had to change directory in
our search for debian/changelog. This is the default behaviour.
=item B<2>
Always check the directory name.
=back
The directory name is checked by testing whether the current directory
name (as determined by L<pwd(1)>) matches the regex given by the
configuration file option C<DEVSCRIPTS_CHECK_DIRNAME_REGEX> or by the
command line option B<--check-dirname-regex REGEX>. Here regex is a Perl
regex (see L<perlre(3perl)>), which will be anchored at the beginning
and the end. If regex contains a '/', then it must match the fulla
directory path. If not, then it must match the full directory name. If
regex 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.
The default changelog to be edited is F<debian/changelog>; however,
this can be changed using the B<--changelog> or B<--news> options or
the C<CHANGELOG> environment variable, as described below.
=head1 OPTIONS
=over 4
=item B<-a, --append>
Add a new changelog entry at the end of the current version's entries.
=item B<--allow-lower-version>
Allow a version number to be less than the current one if the new
version matches the specified pattern.
=item B<--auto-nmu>
Attempt to automatically determine whether a change to the changelog
represents a I<Non Maintainer Upload>. This is the default.
=item B<-b, --force-bad-version>
Force a version number to be less than the current one (e.g. when
backporting).
=item B<--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.
=item B<--bpo>
Increment the Debian release number for an upload to lenny-backports,
and add a backport upload changelog comment.
=item B<-c, --changelog FILE>
This will edit the F<changelog> file instead of the standard
F<debian/changelog>. This option overrides any C<CHANGELOG>
environment variable setting. Also, no directory traversing or
checking will be performed when this option is used.
=item B<--check-dirname-level N>
See the above section "Directory name checking" for an explanation
of this option.
=item B<--check-dirname-regex REGEX>
See the above section "Directory name checking" for an explanation
of this option.
=item B<--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 B<--noquery> has not been specified), or
if there are problems with the bug report located.
=item B<--create>
This will create a new F<debian/changelog> file (or I<NEWS> if the
B<--news> 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 B<--package> and
B<--newversion> options, determined from the directory name using the
B<--fromdirname> 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 B<--distribution> option or in the generated changelog file.
=item B<-d, --fromdirname>
This will take the upstream version number from the directory name,
which should be of the form I<package-version>. If the upstream
version number has increased from the most recent changelog entry,
then a new entry will be made with version number I<version-1> (or
I<version> 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 option B<-i>.
=item B<-D, --distribution DIST>
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.
=item B<-e, --edit>
Edit the changelog in an editor.
=item B<--empty>
When used in combination with B<--create>, suppress the automatic
addition of an "initial release" changelog entry (so that the next
invocation of debchange adds the first entry). Note that this will
cause a L<dpkg-parsechangelog(1)> warning on the next invocation due
to the lack of changes.
=item B<--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).
=item B<--force-save-on-release>
When B<--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)
=item B<-h, --help>
Display a help message and exit successfully.
=item B<-i, --increment>
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.
=item B<-l, --local, SUFFIX>
Add a suffix to the Debian version number for a local build.
=item B<-m, --maintmaint>
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.
=item B<--[no]multimaint>
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 C<DEBCHANGE_MULTIMAINT> configuration file option below.
=item B<-n, --nmu>
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 F<debian/control>, unless
C<DEBCHANGE_AUTO_NMU> is set to no or the B<--no-auto-nmu> option is used.
=item B<--news [newsfile]>
This will edit newsfile (by default, F<debian/NEWS>) instead of the
regular changelog. Directory searching will be performed. The
changelog will be examined in order to determine the current package
version.
=item B<--no-auto-nmu>
Disable automatic NMU detection. Equivalent to setting
C<DEBCHANGE_AUTO_NMU> to I<no>.
=item B<--no-conf, --noconf>
Do not read any configuration files. This can only be used as the
first option given on the command line.
=item B<--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. B<debchange --release "">. The
entry will not be added to the changelog but its presence will
suppress the editor.
=item B<--no-preserve>
Do not preserve the source tree directory name (default).
=item B<-p, --preserve>
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.
=item B<--package PACKAGE>
This specifies the package name to be used in the new changelog; this
may only be used in conjunction with the B<--create> and B<--increment>
options.
=item B<-q, --qa>
Increment the Debian release number for a Debian QA Team upload, and
add a QA upload changelog comment.
=item B<--[no]query>
Should we attempt to query the BTS when generating closes entries?
=item B<-r, --release>
Finalize the changelog for a release. Update the changelog timestamp.
If the distribution is set to I<UNRELEASED>, change it to the
distribution from the previous changelog entry (or another
distribution as specified by B<--distribution>). If there are no
previous changelog entries and an explicit distribution has not been
specified, I<unstable> will be used.
=item B<--release-heuristic LOG|CHANGELOG>
Controls how debchange determines if a package has been released, when
deciding whether to create a new changelog entry or append to an
existing changelog entry.
=item B<-s, --security>
Increment the Debian release number for a Debian Security Team
non-maintainer upload, and add a Security Team upload changelog
comment.
=item B<-t, --[no]mainttrailer>
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.
B<--create>, B<--release>, B<-i>, B<--qa>, etc.) This option differs
from B<--maintmaint> in that it will use multi-maintainer mode if
appropriate, with the exception of editing the trailer. See also the
C<DEBCHANGE_MAINTTRAILER> configuration file option below.
=item B<-u, --urgency URGENCY>
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.
=item B<-v, --newversion VERSION>
This specifies the version number (including the Debian release part)
explicitly and behaves as the B<--increment> option in other respects. It
will also change the directory name if the upstream version number has
changed.
=item B<--version>
Display version and copyright information and exit successfully.
=back
=head1 CONFIGURATION VARIABLES
The two configuration files /etc/devscripts.conf and F<~/.devscripts>
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 listed below.
=over 4
=item B<DEBCHANGE_PRESERVE>
If this is set to yes, then it is the same as the B<--preserve> command
line parameter being used.
=item B<DEBCHANGE_QUERY_BTS>
If this is set to no, then it is the same as the B<--noquery> command
line parameter being used.
=item B<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 devscripts scripts which
check their value, as described in their respective manpages and in
L<devscripts.conf(5)>.
=item B<DEBCHANGE_RELEASE_HEURISTIC>
Controls how debchange 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 I<log> or I<changelog>.
=item B<DEBCHANGE_MULTIMAINT>
If set to I<no>, debchange will not introduce multiple-maintainer
distinctions when a different maintainer appends an entry to an
existing changelog. See the discussion above. Default is I<yes>.
=item B<DEBCHANGE_MULTIMAINT_MERGE>
If set to I<yes>, when adding changes in multiple-maintainer mode
debchange 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 I<no>.
=item B<DEBCHANGE_MAINTTRAILER>
If this is set to I<no>, then it is the same as the
B<--nomainttrailer> command line parameter being used.
=item B<DEBCHANGE_TZ>
Use this timezone for changelog entries. Default is the user/system
timezone as shown by command C<date -R>.
=item B<DEBCHANGE_LOWER_VERSION_PATTERN>
If this is set, then it is the same as the B<--allow-lower-version>
command line parameter being used.
=item B<DEBCHANGE_AUTO_NMU>
If this is set to I<no> then debchange will not attempt to
automatically determine whether the current changelog stanza
represents an NMU. The default is I<yes>. See the discussion of the
B<--nmu> option above.
=item B<DEBCHANGE_FORCE_SAVE_ON_RELEASE>
If this is set to I<no>, then it is the same as the
B<--no-force-save-on-release> command line parameter being used.
=back
=head1 ENVIRONMENT
=over 4
=item B<DEBEMAIL, EMAIL, DEBFULLNAME, NAME>
See the above description of the use of these environment variables.
=item B<CHANGELOG>
This variable specifies the changelog to edit in place of
F<debian/changelog>. No directory traversal or checking is performed
when this variable is set. This variable is overridden by the
B<--changelog> command-line setting.
=item B<VISUAL, EDITOR>
These environment variables (in this order) determine the editor used
by L<sensible-editor(1)>.
=back
=head1 SEE ALSO
L<debclean(1)>
L<dupload(1)>
L<dput(1)>
L<debc(1)>
L<devscripts.conf(5)>
=head1 AUTHORS
Program was written by Christoph Lameter <clame...@debian.org>. Many
substantial changes and improvements were made by Julian Gilbey
<j...@debian.org>.
=cut
