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.
Additionally, it provides
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.
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:
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.
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:
Technical University Berlin
Computer Science, Secr. FR 5-6
D-10587 Berlin, Germany