Ubuntu Manpage: shape_releas - shapeTools RMS construction of releases and prereleases

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

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO