Release Management

[Todd Caine]

Just in case anyone else is interested......


The Terminator Rat wrote:

Hi, Todd.

I've read a few books and done release management for a few
projects, but
I wouldn't say I'm an expert.  Like my friend Kelly Russell once
said,
"I'm not an actor, but I play one on T.V.".

You should *not* check in the Solaris package, since it is
merely a way of
repackaging the repository's sources.  However, you probably
want to make
a "release" target in your Makefile or a "mk_release" script
that builds
the package for you.  This will ensure that you can recreate the
package
with the same arguments and files at a later date.  Be sure to
specify the
sources by name (don't just use '*.pl', for instance) so that
the file
list in the package will be consistent.

You should use branches to manage bug-fixes and other mods on
released
software.  Don't forget to baseline each branch, or you'll have
trouble
pulling up the fixes to the mainline.

When building your package, you want to create a virgin source
tree and
populate it with CVS export.  For instance:

        rm -rf build
        mkdir build
        cvs export -d build -r release_1_2_3 project
        cd build
        make release

Of course, all of the above could be built into the 'release:'
target in
the Makefile or your mk_release script.

Version numbering is more art than science (and pop art at
that).  The
first official public release is usually 1.0, but that can
vary.  The
defacto standard for version numbering is :

        major.minor.[p[patchlevel]]

The patchlevel is typically bumped when a bug fix is made.  The
minor
number is usually bumped when significant new functionality is
added.  A
change in the major number usually indicates extreme changes
from the
previous version (i.e. a re-write or re-design).

Don't forget that CVS doesn't allow you to use '.' in symbolic
or branch
tags -- substitute them with '_' characters.  For example,
release 1.2.3
becomes "release-1_2_3".

When I was doing release management on the PIX, we bumped the
software
from 3.4 to 4.0 because Checkpoint had bumped Firewall1's major
number.
The differences between the two "major" versions was minimal,
but the
marketing department thought it was something of a coup.  Not
that I'm
suggesting doing this, but it's a good illustration that version
numbering
isn't entirely a technical issue.

Keeping README and CHANGES files is often sufficient for
documenting the
changes made to the release.  You can generate the CHANGES file
after the
fact if necessary.  An easy way to do this is to browse through
the commit
history since the last release.

Alternatively, create a diff against the previous release and
note the
changes made.  Obviously this is much more time-intensive, but
you'll
catch things that didn't make it into the commit history (and
miss things
that did).

To go back on my word above, you may wish to keep a directory
somewhere in
the repository that contains the packaged software for each
release. For
instance, create a 'dists' module and check in each new
distribution file.
Be sure to turn off keyword expansion ('cvs add -kb') on the
distfiles to
prevent them being corrupted by RCS keyword expansion.  Check
them in with
the name they were distributed by (i.e. 'foo-1.2.3.tar.gz').
This is much
more useful in the long run than patching the previous binary.

Another very cool and handy thing you can do is add build
information to
the binary so you can identify the exact rev and build of the
software at
a later date.  A common way to do this is to build a target into
your
Makefile that updates build information in the package.

<ELI> There's a good example of adding build information in the
Jufitsu
sources -- in particular, look at how the Makefile runs
newvers.sh to
create vers.c. </ELI>

A similar thing would be very simple in Perl.  The following is
quite
handy in Perl for single-script programs:

        use vars        qw/ $VERSION /;
        my $REVISION = '$Revision: 1.67 $';
        ($VERSION)   = $REVISION =~ m/: (\S+)\ \$$/;

Then you can arrange for your script to print the version if
requested. In
this case, you are making the script's version an identity with
the file's
revision number.  The RCS $Name$, $Author$ and $Date$ strings
could also
be used to build up a build/release information string.

Probably the two most useful things you can do are to create and
maintain
a CHANGES file, and automate the release process as much as
possible.  In
an ideal world, after getting the green-light from your testers,
you would
just "make release" and hand the package to whoever does your
distribution
(i.e. your FTP site, mail it out on CD-ROM's, etc).

Hope that helps,

        -r

On Wed, 19 Sep 2001, Todd Caine wrote:
 > I am trying to figure out best practices for managing
software in a team
 > environment.  Currently we are using CVS for revision
control.  There is no
 > defined way to release software, besides cutting a formal
release via CVS
 > and tar'ing it up.  I just finished a project and have
created a release in
 > CVS.  I then exported the software to a directory in /tmp
where I built a
 > Solaris package.  Should the package stream be checked into
the repository
 > as well?  Should it be under the same CVS module?  Even after
I cut a formal
 > release (branch and base tags)?  Does anyone have any
suggestions for
 > selecting version numbers?  Are README and CHANGES files
sufficient for
 > proper documentation?  I guess I'm just not aware of how
release management
 > is done in other shops.  Any feedback would be greatly
appreciated.
 >
 > Thanks in advance.
 > Todd
 > .
 >
====================================================================

 > =  GEekList  -- GeEk oF thE WorLd UniTed --    Techie
forum        =
 >
====================================================================

 > .
 >

--
O----O  Karl F. Schilke - rat at cynical dot org -
http://www.cynical.org/~rat
 \oO/
==\/==     "If I was just half the man he is ... I'd probably
fall over."



TIMTOWTDI