CM.RELNOTES.SH(1)
NAME
cm.relnotes.sh - create release notes from bug records
SYNOPSIS
cm.relnotes.sh [-t] [-d YYMMDD] [-r releasenum] [-l printer
| -f filename]
DESCRIPTION
Use cm.relnotes.sh with a Configuration Management System to
generate a set of product release notes. The cm.relnotes.sh
utility reads bugids from stdin and writes the report to a
printer or a file. By default, the report is written to the
default printer used by lp(1). In general the bugids are
generated by a query of a Configuration Management system.
For example, a query of a CM system (such as ClearCase) can
generate a list of all the bugids associated with the files
that comprise a release or a configuration. The
cm.relnotes.sh utility takes that information and
information in the ClearDDTS database and creates the
release notes.
cm.relnotes.sh is implemented as a bourne shell script so
that it is user configurable. See the beginning of the
script for allowable customizations.
By default, cm.relnotes.sh takes a list of bugids and splits
them up into two groups: actual defects repaired and
enhancements. A third list is created by finding the
unresolved defects associated with the projects defined by
the bugids on stdin. All unresolved defects as of the
release date, YYMMDD, are included and all bugs submitted
after that date are ignored. This gives a historically
accurate list of unresolved defects as of the release date.
(Even if the bug is currently resolved.)
The three lists of bugids are used to create 7 sections of a
Release Notes Document. (See list below.) The document
will contain one title page, three summaries, and individual
defect reports for each summary section.
Options
-d YYMMDD Allows the specification of a release date.
The cm.relnotes.sh utility can reconstruct a
historically accurate list of Resolved and
Unresolved bugs as of that date. If a defect was
unresolved at that date and has been subsequently
resolved it will appear in the table of contents
and the full page report as an unresolved defect.
Note that if you pass in a defect identifier that
was unresolved as of this date, cm.relnotes.sh
will not include it with the resolved bugs. The
default is to make the release date today.
-f filename Allows redirecting the output to a file. It is
mutually exclusive with the -l option. The
filename is used as a prefix. Suffixes .1 through
.7 are used for the different portions of the
report as defined below:
1 Title page in troff format.
2 Table of contents for enhancements in troff format.
3 Full page reports for enhancements in (ASCII) format.
4 Table of contents for defects repaired in troff format.
5 Full page reports for defects repaired in (ASCII) format.
6 Table of contents for unresolved defects in troff format.
7 Full page reports for unresolved defects in (ASCII) format.
-l printer Allows the specification of the printer name.
This option is mutually exclusive with the -f
option. If unspecified, the default printer is
used.
-r releasenum Allows the specification of a release number,
like 3.0.14A. This is only used in printing the
title page. The default is to print "Version:
Latest".
-t Only generate the title page and the three tables
of contents, suppressing the full page reports.
This option saves considerable execution time and
paper.
EXAMPLES
The cm.relnotes.sh utility is meant for use with a CM system
where the CM system provides the list of bugids on stdin via
a query about a configuration or a release. For example, if
foo produces bugids for all changes between this release and
the previous one, then the following produces release notes
for the new release and sends it to the default printer:
foo | cm.relnotes.sh
If a few days later you want to generate it again with a
version number, then do:
foo | cm.relnotes.sh -d 931001 -r 3.0.14A
If your CM system can not produce a list of resolved defects
associated with the checked in files, you can simulate this
with findbug like:
findbug -RV Submitted-on > XXYYZZ \
| cm.relnotes.sh -d AABBCC -r "The Mumble Release"
This command finds resolved bugs Submitted after the date
XXYYZZ. It is important to specify a Submitted-on date
unless you would like to see all the bugs that have been
submitted against the product. These defects are piped into
the cm.relnotes.sh script to produce the report of bugs
resolved as of AABBCC.
The findbug(1) script simulates a query of the CM system to
find all of the defects resolved during that release of the
project. Normally these resolved defects would be found by
a query of the CM system. That is, a file checked into the
CM system is usually checked in on behalf of a resolved
defect. Note that there is an advantage of using this
method over generating the defect list from the CM system.
This method will find all resolved defects (manuals, config
files, etc) not just defects reported and resolved that were
entered into the CM system.
WARNINGS
cm.relnotes.sh does a large amount of formatting to make the
release notes, and therefore should be used with care.
Doing a one hundred bug summary can take 150 pages of paper
and 10 minutes to produce. Using the -t option will
considerably decrease the processing time and paper
generated.
SEE ALSO
findbug(1), sortbug(1), dumpbug(1), troff(1),
cm.release.sh(1)