Provided by: shapetools_1.4pl6-16_amd64 bug

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)