NAME
shape_releas - shapeTools RMS construction of releases and prereleases
SYNOPSIS
shape prerelease
shape release
shape plprerelease
shape plrelease
shape extractrelease [RELEASENAME=<releaseId>] [(PARTIAL)RELEASEBASE=<path>]
DESCRIPTION
The heart of the shapeTools Release Management System is its mechanism
for creating prereleases and releases of the managed software system.
These functions can be invoked from any node of the system source
repository and from any private workspace. Hence, each node system can
be (pre)released independently. Constructing a (pre)release of a
non-leaf node (a node containing no subsystems) requires all subsystems
to be (pre)released beforehand and incorporates the existing
(pre)releases in the new (pre)release.
Prereleases are part of the systematic preparation of a release. They
give a glance on how a release will look like in the current
development state. They should be used for internal publication and
integration testing. When a prerelease has proved to be stable enough
to be released to the outside world, it should be declared as new
system release. This mechanism allows an arbitrary number of release
test cycles without prematurely using the anticipated release number.
The general algorithm of the shape_RMS release functions is the
following.
1) check release preconditions
Before a release process is sent on its way, the system is checked
for releasability. If any of the required preconditions is not met,
the system is not releasable and the release process stops. First,
each subsystem - if there are any - has to be (pre)released
beforehand. Release building requires all subsystems to be
released, prereleases need the subsystems to be prereleased. The
second condition, only applying to prereleases, requires that no
foreign update locks are active on any of the components going into
the (pre)release. It is advisable, that no changes to any of the
node components are unsaved (pending), no matter who is the author.
However, if the user who triggered the release process has pending
changes on any components to be released, these will be saved
automatically and the update locks given up. Pending changes with
update locks by other users let the release process fail.
2) generate release name
Each release and prerelease has an identification string, built
from the node name and a two part release number. Prerelease names
additionally contain a prerelease serial number, Patchlevel
releases and prereleases also the patchlevel number. The release
number is taken from the node’s automatically maintained release
identification file. The generated release identification string is
tagged to any component being part of the (pre)release.
3) invoke releases of subsystems
Prereleases and releases invoke all subsystems of the current node.
Prerelease building includes the most recent prerelease of each
subsystem, while release building includes the most recent
subsystem releases. Each of the subsystem components get,
additionally to the subsystem release name they already have, the
freshly build release name tagged on as symbolic name. Symbolic
names may be used as surrogates for version numbers (see vadm(1)).
4) save release components and set attributes
After all components of the included subsystems have been marked,
all direct parts of a the released node get the release
identification string as symbolic name. In case of building a
prerelease, if any of the direct components has a busy version
differing from the last saved version (pending changes) and an
update lock set by the user who triggered the prerelease building,
it is saved automatically before (see also 1. ). All node component
versions (from subsystems or direct components) are additionally
set to an appropriate version state (see below).
5) install components in release area
The last step is the installation of all marked component versions
(subsystem components and node components) in one of the two
release areas. Releases and prereleases that have been made from
the top node of the source repository are copied to the release
area. All other releases, representing only a part of the whole
development, are installed in the partial release area.
Shape prerelease saves the current state of development. According to
the algorithm described above, all unsaved node system components are
saved and the most recent version of each component is included in the
new prerelease. A prerelease additionally invokes the most recent
prerelease or release (whichever is the newest) of each subsystem. All
component versions going into the prerelease may further be identified
by the automatically generated prerelease name, having the form
<system_name>-<generation>.<revision>pre<prerelease_number> (e.g. shapeTools-1.3pre5).
The prerelease serial number is maintained automatically. It starts
with 1. All prerelease component versions are set to the state
proposed. Prereleases of the whole system (the prerelease action was
invoked from the top node) cause all component versions be set to state
accessed. A copy of the prerelease is extracted from the source
repository and established installed in either the release area of the
partial release area, depending on whether the prerelease comprises the
whole system of or just a part.
Shape release declares a previously constructed prerelease as new
release. The most recent prerelease of the current node is taken as
basis. If the node contains subsystems, shape release requires the most
recent release of each subsystem to be included. If any subsystem has a
prerelease more recent than it’s last release, shape gives a warning
and asks for confirmation to proceed. Due to technical reasons, it
does this for each component. Don’t get confused when you have to
confirm multiple times. The new release gets a name of the form
<system_name>-<generation>.<revision> (e.g. shapeTools-1.3).
The generation and revision number are derived from the system’s
automatically maintained release identification file. With each
release, a new version of this file is created. Declaring a new
generation for the release file (see Save(1)) increases the system
generation number. All component versions of the release are set to
state published, except when a releases of the whole system is
constructed (shape release from the system tree top node). In this
case, the state of all component versions is set to frozen. Like
prereleases, a copy of the release is extracted from the source
repository and written to one of the release area or the partial
release area.
Shape plprerelease and shape plrelease (shape patchlevel(pre)release)
are basically the same as prerelease and release. The only difference
is the form of the identification string. Patchlevel prereleases are
named
<system_name>-<gen>.<rev>pl<patchlevel>pre<prerel_num> (e.g. shapeTools-1.3pl5pre2)
and patchlevel releases
<system_name>-<gen>.<rev>pl<patchlevel> (e.g. shapeTools-1.3pl5).
The idea of patchlevel releases is to construct releases that are not
to be shipped completely but rather as a patch to an existing release.
Of course, real releases may also be shipped as patches, so this is
rather a naming convention.
Shape extractrelease extracts a copy of a certain release or prerelease
from the project’s central source repository and installs it in the
release area or the partial release area (depending on whether it is a
(pre)release of the whole system or just a part of the system). When
called without further settings, it installs the most recent
(pre)releases. The installed copy represents a source distribution of
the system or system part. It is totally independent of the development
environment.
An explicit release identification may be given to shape extractrelease
by setting RELEASENAME=<release_identification> on the command line.
Setting one of the macros RELEASEBASE or PARTIALRELEASEBASE on the
command line redefines the path to the base directory of the release
tree. (Pre)releases of the whole system are copied to RELEASEBASE, all
others to PARTIALRELEASEBASE. Check your Shapefile for the default
settings of these two macros. Subdirectories will be automatically
created there as needed.
FILES
Shapefile
SEE ALSO
shape_RMS(1)