Tag & Release Policy

This document summarizes how the release mechanism in Geant4 is supposed to work. It also has to be considered a reference-guide for all G4 category coordinators in order to make this mechanism work properly and succefully.

Introduction.
The GEANT4 release policy.
Duties of a Category Coordinator.
Duties of the Release Coordinator.

1. Introduction

Geant4 is composed by several class categories (or sub-domains or components). Each sub-domain is associated to a CVS directory (which can be composed by sub-directories) within a single CVS module.

Each category should represent a well encapsulated set of classes with specific functionalities. It contains a set of tests, aiming to cover the functionalities of all the classes contained there (on average it can be one test per class).

Each category is under the control of a category (or working group) coordinator (one or more) who is (are) responsible for the functionalities associated with his (their) sub-domain.

Each working group is in charge of writing, maintaining and running all the tests belonging to the corresponding directory.

Each working group is also required to frequently provide tagged, validated versions of its directory (no need to be coincident with the HEAD of the repository), which can be used by all the other working groups.

A "System Testing Team" (STT) is in charge of developing and maintaining the set of global tests or System tests (i.e. tests placed in the "tests" tree, which is supposed not to be part of a public release). The global tests are meant to verify and validate the overall functioning of GEANT4 for several different types of applications (i.e. EM showers, hits production and persistency, tracking of geantinos in B field, fast parameterisations, etc.), therefore covering as many functionalities as possible.

An additional "Examples Working Group" is in charge of developing and maintaining the set of global examples or Acceptance tests (i.e. examples placed in the "examples" tree provided with the public distribution of the toolkit). The functionalities covered by the global examples are supposed to be a subset of those covered by the global system tests.

Finally, each global test must have a reference-input and a reference-output. The result of each global test can be compared to the reference output. The comparison with the reference output has to be automated, so that the answer of each global test will be a Boolean (like OK or FAILED).

In case of global tests or examples which cannot be completely automated (i.e. tests or examples involving graphics or DB access), the "System Testing Team" and/or the "Example Working Group" in Geant4 is responsible of assuring the correct functioning.

2. The GEANT4 release policy

A general release of the Geant4 Toolkit has to be performed at the dates established in the milestones within the Collaboration.

A general release is a collection of all announced category tags approved by the "System Testing Team". It will be effective after the bug-fix phase has taken place on the CVS branch created by the STT (see page on the system testing procedure).
It will collect related documentation tags as well.

During the release phase, bug-fixes may take place on the branch until all system tests and acceptance tests are evaluated to be positive on the supported platforms/compilers. During the bug-fix phase preceding the release, and during the release phase, developers can continue normal development on the HEAD of the main CVS trunk.

It is IMPORTANT that all general functionalities of the Toolkit (represented by the current system and acceptance tests), are correctly performed by a "stable" release of Geant4. A version of the Geant4 Toolkit should be officially released only when this condition is satisfied.

A release should be portable and successful on all Geant4 supported platforms/compilers, namely:

IBM-AIX (xlC compiler);
HP-UX (aCC compiler);
DEC-OSF (cxx compiler);
SGI-IRIX (CC compiler);
SUNOS5 (CC compiler);
Linux (g++/egcs compiler);
Windows/98/NT (MSVC++ compiler).

3. Duties of a Category Coordinator

For a category coordinator, being responsible for the functionalities of his sub-domain means:

keep up-to-date his own test-release of Geant4 with the last release of the Toolkit and possible newer tags of co-working categories (it might be required to modify and tag also other categories at the same time);
assure that all internal tests for the detailed functionalities of the category, work properly and give the correct results;
assure that the category co-works properly with the other categories in the current release or newer (i.e. it would be VERY useful and appropriate to CHECK that the most relevant global-examples work properly and give the correct results);
perform the tests on AT LEAST TWO supported platforms;
commit & tag the category's code and related documentation tree, after having properly updated the "History" file;
announce the tag to the "System Testing Team" (geant4-stt@listbox.cern.ch) which will then take care of testing the new tag and, if approved, announce it to the G4 Web Blackboard - "Tags & Releases announcements" section. The category coordinator should message to the STT the following information: the tag-name, the possible co-working categories tags and the TWO supported platforms where the tests have been performed;
if bugs/errors reported by STT affect his category, the category coordinator must promptly start the process to fix them, re-tag and re-announce his category in time for the "bug-fix" release phase;
during the "bug-fix" phase, the category coordinator must promptly cooperate with the STT on fixing those bugs/problems possibly affecting his category, by committing the fix on the branch (and also possibly on the HEAD of the main CVS trunk) within 24 hours.

Whenever a modification in a specific category involves the interface between other categories (design changes), the category coordinator is responsible for notifying the changes needed to be done to the other categories and possibly apply them (pending approval of the other category coordinators). In this special case, the category coordinator is responsible also to test the functionalities of all affected categories AND the global examples, in cooperation with several category coordinators.

4. Duties of the Release Coordinator

The release coordinator is responsible for:

Build a major release of the toolkit on those reference platforms/compilers as agreed with the System Testing Team. This means, in detail:
- Compile all the last versions of the sub-domains approved by the "System Testing Team", starting from the branch, verifying if they indeed are consistent with each other at the compiler level;
- Compile and link all the system tests, verifying if the full code is indeed consistent at the linker level;
- Run the system tests, verifying if the code covered by the tests is indeed consistent at run-time (automated process).
Publish the results of the build to the tagging mail-list (geant4-tag@listbox.cern.ch).
Publish a summary when the final release is ready.

The following are NOT the tasks of the release coordinator:

Fix bugs (he can collaborate/or point to a solution if the bug is obvious);
Porting of the code to new architecures;
Maintain the overall infrastructure (i.e. GNUmakefiles and related directory hierarchy);
In case of failure of a system test, examine the detailed output of the test (if any) and/or identify possible causes of the failure.

The release coordinator should be involved when major modifications to the infrastructure of the toolkit must be applied. In that case, a pre-release preceeding the re-organisation should be applied and either one of the following two actions should be performed:

stop development for a reasonable amount of time (few hours) to allow the migration;
or create a brand NEW CVS module.

Wed 16 Sep 1998, GC