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)