Ubuntu Manpage: shape_RMS - Introduction to the shapeTools Release Management System

NAME

       shape_RMS - Introduction to the shapeTools Release Management System

SYNOPSIS

       shape rms - show synopsis of shapeTools Release Management System Functions

DESCRIPTION

The shapeTools Release Management System (shape_RMS) helps constructing and keeping track
of system releases in complex (multi programmer) software development projects. This
introductory manual page gives an overview of the shape_RMS functionality and helps
getting started with the release management system. When reading this introduction, you
should either be familiar with the basics of the shapeTools version control system and the
shape configuration management program, or you should have the shapeTools version control
and the shape(1) manual pages at hand. Complementary to this short reference manual page,
there is a tutorial introduction to the usage of shapeTools, explaining how to introduce
and use the shape-toolkit's functionality cleverly in a multi programmer project.

The cooperation and release management model of a software development project is highly
dependent on the nature of the project. Factors like the programming language used, the
size of the programmer team, the nature of the developed software, or local preferences
strongly influence this model. The release management system as currently implemented,
will in most cases not fit all your needs. Take it as a prototype to begin with and try
to adapt it little by little. In the current state, modifying the release management
system requires good skills in Makefile and Shapefile writing and a lot of patience. Think
twice about every modification you perform ! Establishing a good cooperation and release
model is not as easy as it might look like at the first glance.

The shapeTools RMS imposes a general frame for the project structure and the development
process within a software development project. This frame is necessary for the release
management system to determine it's workpieces and to be able to systematically document
the evolution of system configurations. It helps the developer to have all system
configuration and building actions performed automatically, so that he can concentrate on
his development work, rather than code management activities.

All functions of the shapeTools RMS are performed by the shape(1) program. This
interprets a description file (the Shapefile) and performs the action associated with a
target name given with the shape call. Usually, you may perform a bunch of macro
definitions together with the shape call. These definitions overwrite internal default
macro settings. Hence, calls of the shape_RMS have the general form
shape target [MACRONAME=value ...].

In detail, shape_RMS automatically performs the following actions, each of which is
described on the referenced manual page.

•
System building, installation, and cleaning up (shape_build(1)).

•
Generation of prereleases of subsystems or the whole system (shape_releas(1)).

•
Generation of releases of subsystems or the whole system (shape_releas(1)).

•
Constructing patches to existing releases (shape_patch(1)).

•
Reinstantiation of old system releases (shape_releas(1))

•
Creation of shippable packages (tar or shar files, etc.) (shape_tar(1)).

•
Determination of file dependencies (shape_depend(1)).

Additionally, it provides

•
Standard version selection rules (shape_stdrul(7)).

•
A project wide unified variant control raster (shape_stdvar(7)).

•
Automatic generation of (pre)release identifications.

•
Storing configuration management specific information with each system component.

•
Templates for Shapefiles and Makefiles (shape_tmpl(7)).

The Project Structure

The general project structure is hierarchical. Each node in the hierarchy consists of a
number of components and a number of subsystems. The top node in the hierarchy represents
the whole system. These three terms - node (or system node), component and subsystem -
will be used throughout all shape_RMS manual pages. A subsystem and a system node are the
same thing in principle, consisting of components and subsystems. The notions rather
distinguish two different points of view.

The hierarchical structure is reflected in a UNIX directory tree with directories
representing nodes and files as system components. Not each directory necessarily holds a
whole system node. Single nodes may spread across multiple directories forming a subtree.
The top directory of this subtree is the representant of the node. Hence, the system
structure and the directory tree may differ.

The project structure and it's components is described by the system model. The system
model consists of a interwoven collection of Shapefiles and Makefiles. Each node is
equipped with one Makefile and one Shapefile containing node specific system model
information. Additional system model information (such as standard version selection rules
or project wide variant definitions) is maintained in a project wide central place and
accessed through shape's include facility.

The functional profile of the system model is reflected by predefined standard targets in
the system model files (Shape- and Makefiles). These targets are defined either in the
individual (node specific) Shape- and Makefiles or in one of the included Shapefile
fragments maintained project wide Shapefile. A set of standard macros and implicitly a set
of conventions that underlie those macros comprise the data interface between the various
modules of the system model. Conformance with the necessary underlying conventions and
assumptions is facilitated by templates for Shape- and Makefiles that are provided to the
programmers of the various system parts (see shape_tmpl(7)). Using these templates makes
writing system model information almost trivial.

According to the templates, the Makefile components contain most macro definitions, the
usual component dependency definitions and most of the explicit transformation rules. The
system of Makefiles is carefully designed to be selfcontained enough to be used without
shape(1). This is necessary to provide a build procedure for compiling and installing
software system outside the development area (where shape(1) usually is not available).

The Shapefile components contain information that is specifically related to shape's
special features that are unavailable in make (e.g. version selection, variant handling).
The complete system of Shape- and Makefiles is free of redundancy, making them easier to
maintain. The Shapefiles, in order to represent a complete system model, contain include
directives to include all significant system model information that is stored in other
objects, namely the centrally maintained include files and the Makefiles.

The development work usually happens in the developers' private workspaces, with the
results gathered in a central location, the projects source repository. The source
repository is a complete directory tree (complete in the sense of incorporating each
developed system node) representing the whole project. Private workspaces and
corresponding subdirectories in the source repository are linked together by common AtFS
subdirectories (see vcintro(1)) holding all saved work results (versions). This mechanis
makes files from a private workspace get visible in the source repository, as soon as the
developer saves a copy of a file using the shapeTools version control system. Development
work may also happen in the source repository. In this case, even the busy version of each
workpiece is visible in the source repository, which doesn't disturb.

Each node in the system must contain a release identification file. This file is
maintained automatically and should never be modified manually. It is also to be derived
from a given template and contains a string citing the node name and the actual release
number. With each new release, a new version of the release identification file is
generated. In software development, it typically contains a routine returning the release
identification string mentioned above. This mechanism automates release identification in
software systems.

Beside private workspaces and source repository, a project has a partial release area and
a release area. Both areas are capable to hold a complete copy of the project's source
tree as UNIX files (without version control). The partial release area holds the most
recent (pre-)release of each system node. Every time, a system node gets prereleased or
released, a copy of the involved source versions is written to the partial release area.
The release area holds prereleases and releases of the whole system. It is only filled,
when a (pre-)release building procedure is triggered from the top node of the source
repository. You find some more details on this topic in the shape_releas(1) manual page.

The Development Process

The general development process imposed by the shape release management system is
described by the following pattern.

1)
local development and test in private workspaces with local versions (save)

2)
individual prepublication of single node system (node prerelease)

3)
global integration and integration testing (top prerelease)

4)
incorporation of change requests from global integration into single node systems and
final publication of node systems (node release)

5)
global release (top release)

6)
local introduction of bug fixes in the released system (node patch prerelease).

7)
global integration of patches and integration testing (top patch prerelease).

8)
local releases of patched node system releases (node patch release).

9)
generating a global patched release (top patch release).

Of course, there may be several loops in the above list. First, the construction of node
(pre-)releases happens recursively from the leaves of the system source tree to the top.
Second, several iterations of the node/top prerelease mechanism will usually be necessary,
to come to a stable final release.

Individual development and test happens in private workspaces of individual developers. A
developer typically uses local busy versions and the latest released components of all
other system parts he needs (e.g. libraries) in order to test his component. Intermediate
results of individual development work can be saved into the version base. The
corresponding status of emerging versions is saved.

When the developer thinks that a stable state of development is reached or a development
transaction has been completed he performs an individual prerelease of his work results.
Such a release of work results consists of saving all yet unsaved busy versions into the
version base, marking all components of the worked-upon subsystem (i.e. all most recent
versions) with a common, unique, and well-defined local releasename, and assigning the
status proposed to all these versions. These versions, as residing in the central source
repository are globally accessible for the system integrator.

Global integration and integration testing is performed by a special user, the integrator.
The integrator does typically not do any actual development work himself. In fact the
integrator is a conceptual user (i.e. a special userId) who acts in the central source
repository and hence has access to all individually released components and subsystems of
the developed system. Integration testing gathers all most recent individual prereleases
(of components and subsystems) and creates a prerelease of the developed system. All
components that are part of a prerelease are marked with a common, unique, and well-
defined global prereleasename, and assigned the version status published.

The purpose of pre-releasing a system prior to actually releasing it, is to make sure that
all components interoperate properly, the system installation procedure works properly,
the new release does build, install, and run correctly on all supported platforms without
the risk of assigning (and thereby wasting) the planned official releasename prematurely.
During integration testing, no new features or enhancements should be allowed to be
incorporated into the system. The only sort of modification request that shall be
processed during this phase are bugs in the installation procedure and portability
problems (this includes fixing of bugs that are found during porting).

Once the prerelease cycle has produced a stable state of the entire system, it can be
officially released. The official release procedure is similar to the prerelease
procedure, but marks all components with the planned official releasename, and assigns the
version status frozen to them.

Setting up a Project

In the following you find two checklists. The first one says, what to do when initiating a
project as project administrator. The second one helps , connecting to an established
project as developer.

Checklist for initial setup:

A1)
Create a (UNIX) user to be project owner. This should be a conceptual user, not a
natural one. The home directory of this user will be the project home.

A2)
Define a project group (in /etc/group) and add all project participants to this group.

A3)
Set up the central project source repository in project owner's home.

• Create development directory

• Create bin, lib and include directory in development directory.

• Install system source tree with src directory in the development directory as
root.

• Create a directory named AtFS in each directory of the system source tree.

A4)
Set up release and partial release areas by creating the directories release and
partial.release in project owner's home.

A5)
Make all previously created directories group-writable.

A6)
Create a directory named shape in development/lib and copy the shape_RMS templates and
include files to that directory.
These are Shapefile.tmpl, Makefile.tmpl, Release.tmpl, release.c.tmpl, stdconf,
stdtargets, stdrules and stdvar.

A7)
Adjust macro default values in Makefile.tmpl and Shapefile.tmpl in
development/lib/shape according to local installation. The shape_tmpl(7) manual page
gives you information about the semantics of each macro definition. The Makefile
template defines

• base paths for source repository, partial release area, release area, and
system installation locations.

• a description of the host system environment.

• tools and tool options to be used.

• libraries to be used.

• default build and installation actions.

A8)
Check the stdvar (project wide variant definitions) file. See shape_stdvar(7) for
more information about this.

If you stick strictly to the structuring and release model as implemented in the templates
and shape include files given in the shapeTools distribution, your job is done now.
Additional adaptations require changes to be performed manually on the files in shape/lib.
Before you do this, we recommend reading the shapeTools tutorial first. Especially the
Makefile template you should set up very carefully. As most make(1) implementations do
not support inclusion of external parts into Makefiles, local Makefiles (derived from the
template) hold a lot of information that should better be maintained centrally.
Modifications to the Makefile template made after having already derived local Makefiles
from it, requires patching the changes into each local Makefile. This is a costly and
error prone job. We recommend to use patch(1) for this, which definitely isn't what you
would desire, but there is no better solution yet.

A9)
define version selection rules

A10)
implement additional actions in stdtargets or stdconf.

A11)
redefine project wide policies in Makefile.tmpl, Shapefile.tmpl, or stdconf.

Don't try to find any additional documentation guiding through points A9-A11. There is
none yet.

Checklist for developers, when connecting to an existing project:

D1)
Make sure to be member of the project group

D2)
Create private development directory/ies

D3)
Connect to the central source repository by establishing a link named AtFS from your
local development directory to the corresponding directory in the central source
repository. This should either be a symbolic link to the AtFS directory there, or, on
systems where no symbolic link facility is available, a file with the appropriate
pathname as contents. The latter will be interpreted by the shapeTools version control
system as surrogate for a symbolic link.

D4)
Copy Makefile.tmpl from project_home/lib/shape as Makefile to your development
direcory and fill in the necessary macro definitions by editing the file. If you
already have a Makefile, don't try to use that further. You will be much more lucky
with a Makefile derived from the template.

D5)
Copy Shapefile.tmpl as Shapefile to your development direcory. Usually, no
modifications should be necessary there.

D6)
Copy one of Release.tmpl or release.c.tmpl as Release, resp. release.c to your local
directory.

D7)
Create an empty Dependencies file and run shape depend (1) afterwards. Check, if your
project setup supports automatic generation of the Dependencies file. If not, you have
to maintain it manually.

D8)
Run shape rms (1) to get a synopsis of the functions provided by the shapeTools
release management system.

ATTRIBUTES

       As  the  shape toolkit has an Attributed Filesystem (AtFS, see afintro(3)) as data storage
       base, shape_RMS stores it's internal management information as attributes attached to  the
       system  components.  Attributes  consist  of  name  and  a  list of values.  Configuration
       management related attributes are

       __SymbolicName__
              Each component version in the system carries  a  set  of  symbolic  names  uniquely
              identifying  the  (pre-)release(s),  it  is part of. This list may be empty, when a
              version was never declared to be part of a (pre-)release.  __SymbolicName__  is  an
              attribute  with  a  special meaning throughout all programs in shapeTools. For more
              information see the -symbolic option of vl(1) and vadm(1).

       nodename
              Is the name of the node system, the component version belongs to as defined in  the
              NODENAME  macro in the subsystem's Makefile. Only the release number generator file
              carries this attribute.

       lastrelease
              The unique name of the last generated prerelease or release.  This  attribute  gets
              attached  only  to versions of the release number generator file. In fact, it makes
              sense only at the most recent version of the release number generator file.

FILES

       Shapefile.tmpl- Template for subsystem specific Shapefiles
       Makefile.tmpl- Template for subsystem specific Makefiles
       stdconf     - standard configuration management tagets
       stdrules    - standard version selection rules
       stdtargets  - common basic targets
       stdvar      - project wide variant raster

AUTHOR