.\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.TH ADECH 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
adech \- update a ChangeLog
.br
.ne 5
.SH SYNOPSIS
.B adech
\*[ade_standard_synopsis_component]
[
.B \-\-program=\fIprogram-name
]
[
.B \-\-comment="\fIcomment-text\fB"
]
{
.B \-\-bump\-\fR{\fBbug\fR|\fBfeature\fR|\fBrewrite\fR}
|
.B \-\-check\-\fR{\fBreleased\fR|\fBunreleased\fR}
|
.B \-\-finalise
}
.I ChangeLog\-file
.br
.ne 5
.SH DESCRIPTION
.B Adech
updates, checks or finalises release stanzas in ChangeLog files. It is
intended to enforce a strict and machine-parsable format for ChangeLogs.
It was inspired by 
.B dch\fR(1),
which provides a similar purpose for Debian packages' changelog files.
.PP
The path to the ChangeLog file must be specified on the command line.
.PP
.B Adech
takes care of deciding new version numbers, based on whether a release is
to address a bug, the addition of a new feature, or for a total rewrite
of the code. For this reason, 
.B adech
generates version numbers of the form 
.I X.Y.Z\fR,
where 
.I Z\fR,
or
.I Z
and
.I Y
may be missing, depending on which component was incremented most recently.
The first version is version 0.
.br
.ne 5
.SH CONFIGURATION
.I ChangeLog\-file
must exist. If it does not then create it by running:
.IP
.nf
.fam C
.B touch \fIChangeLog\-file\fB
.fam T
.fi
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-\-bump\-bug
Check that 
.I ChangeLog\-file
is in a 'soon-to-be-released' state and then create a new release stanza in 
with the last component of the version number incremented. I.e. the 
version changes from 
.I X.Y.Z 
to 
.I X.Y.Z+1\fR,
thereby putting 
.I ChangeLog\-file
in a 'soon-to-be-released' state.
.TP 
.B \-\-bump\-feature
Check that 
.I ChangeLog\-file
is in a 'soon-to-be-released' state and then create a new release stanza in 
with the middle component of the version number incremented. I.e. the 
version changes from 
.I X.Y.Z 
to 
.I X.Y+1\fR,
thereby putting 
.I ChangeLog\-file
in a 'soon-to-be-released' state.
.TP 
.B \-\-bump\-rewrite
Check that 
.I ChangeLog\-file
is in a 'soon-to-be-released' state and then create a new release stanza in 
with the first component of the version number incremented. I.e. the 
version changes from 
.I X.Y.Z 
to 
.I X+1\fR,
thereby putting 
.I ChangeLog\-file
in a 'soon-to-be-released' state.

.TP
.B \-\-program=\fIprogram-name
If
.I ChangeLog\-file
is empty then 
.B adech
cannot derive the name of the program that owns it. In that case this option
must be provided to declare the name of the program.
.TP
.B \-\-comment="\fIcomment-text\fB"
The specified comment text will be written into the changelog entry. The 
default comment is "please change this text!".
.TP
.B \-\-check\-unreleased
Check that 
.I ChangeLog\-file
is in an unreleased state; this is determined by examining the first
line of the file and checking that it is formatted correctly and
contains the word
.B UNRELEASED
in the right place. This option is primarily intended for inclusion
in build scripts.
.TP
.B \-\-check\-released
Check that 
.I ChangeLog\-file
is in an 'soon-to-be-released' state; this is determined by examining the first
line of the file and checking that it is formatted correctly and
does not contain the word
.B UNRELEASED
in the right place. This option is primarily intended for inclusion
in build scripts.
.TP
.B \-\-finalise
Check that the 
.I ChangeLog\-file
is in an unreleased state, remove the word
.B UNRELEASED
and update the date in the first line.
.br
.ne 5
.SH EXIT STATUS
On success
.B adech
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
The following sets up the ChangeLog file for the first ever release:
.IP
.nf
.fam C
.B touch ChangeLog
.B adech --bump-rewrite ChangeLog
.fam T
.fi
.PP
(Actually, whether 
.B \-\-bump\-rewrite\fR,
.B \-\-bump\-feature\fR,
or 
.B \-\-bump\-bug\fR
is used is irrelevant; the first release is always release 0.)
.PP
Once the code has been written and tested and is ready to be released 
then the ChangeLog might be finalised by running:
.IP
.nf
.fam C
.B adech --finalise ChangeLog
.fam T
.fi
.br
.ne 5
.PP
After this one might prepare the tar.gz source bundle, perhaps using
.B adebun\fR(1).
.SH CAVEATS
The number of components in a version number depends very much on local
policy. 
.B Adech
uses three-component version numbers because this is the author's own
preference. Adherence to a user-specified policy will be implemented
at a future date.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B adech\fR.
.br
.ne 5
.SH SEE ALSO
ade-config(1), adebun(1), dch(1), touch(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2011-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]