Tag & Release Policy
This document summarizes how the release mechanism in Geant4 is supposed to
work. It should also be considered a reference guide for all Geant4 category
coordinators in order to make this mechanism work properly and successfully.
- Introduction
- The GEANT4 Release Policy
- Duties of a Category Coordinator
- Duties of the Release Coordinator
- Releases & Tag Formats
1. Introduction
Geant4 is composed of several class categories (or sub-domains or components).
Each sub-domain is associated with a CVS directory, which in turn may be
composed of 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 or coordinators who are responsible for the functionalities
associated with their sub-domain. Each working group is in charge of
writing, maintaining and running all unit 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), in collaboration with the category coordinators,
is in charge of developing and maintaining the set of global tests or
system integration tests (i.e. tests placed in the "tests" tree, which is
not supposed 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 system integration tests.
Finally, each global test and example must have a reference-input and a
reference-output. The result of each global test and example can be compared
to the reference output. The comparison with the reference output has to be
automated as much as possible. In case of global tests or examples which
cannot be completely automated (i.e. tests or examples involving graphics
or DB access), the STT 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 for the Collaboration and formalised by the
Steering Board (SB). A general release might be major or minor,
according to the following definition:
- Major release: represented by the major revision number XX in XX.YY.
A major release may include major changes/updates to the Geant4 code
and public interface changes, which may imply incompatibilities with
user codes based on previous releases. A major release may therefore
require porting of user code. A major release can be performed only
at the established dates fixed by the SB;
- Minor release: represented by the minor revision number YY in XX.YY.
A minor release may include updates, bug-fixes and new features in
the code (including changes to interfaces internal to Geant4), which
do NOT break public interfaces or require porting of user code. A
minor release may be performed on the advice of the release team and
the approval of the SB, when a reasonable number of updates are
considered suitable to be distributed to the public.
The decision to deliver a major or minor release on the established dates
is taken by the SB on the advice of the release team, and determined by:
- the flow of new development and critical updates, and
- the established Working Group milestones for code delivery.
A general release is a collection of all announced category tags approved
by the STT. Every established general release consists of a bug-fix phase
followed by a release phase:
- bug-fix phase: a period of approximately four weeks, during
which three groups of tags are submitted to system testing
sequentially and separately. The groups of tags are formed and
submitted to testing in a temporal sequence dictated by the domain
dependencies defined in the general Class Category Diagram of Geant4
(see page on the system testing procedure). During this period, user
documentation and relevant design diagrams and documents will also
have to be updated, including documentation of new released
features and/or changes and improvements. Changes submitted to the
documentation tree must be notified to the Documentation
Coordinator.
- release phase: begins at the end of the bug-fix phase and lasts
three weeks, during which validation tests and Q/A checks are performed.
During this period, the updated user documentation (user manuals,
software reference manuals, LXR code tree) is also packaged.
During the entire release period (7 weeks), bug-fixes may also take place
on a CVS 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 may
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.
The source code, release notes, data sets and binary libraries for the
supported platforms/compilers are made available for downloading from Web
at the time the release is announced.
Patches to Public Releases
A complete description with examples of the policy applying for patches
is also accessible in a separate document.
Patches to the more recent public releases are made according to the number
and importance of fixes available. Patches should ONLY include fixes, no
new features, classes or interface changes. The decision if and when to
deliver a public patch is taken by the release team in consultation with
the STT and the Category Coordinators involved. The approximate date for
the release of the patch is announced to the SB by the release coordinator
as soon as it can be established.
Q/A and validation tests are performed as for a public release.
A patch is announced by the release coordinator to the user community as for
a public release; source code and binary libraries distributed from the
Web are updated accordingly.
Fixes to be provided as a patch to an existing release XX.YY[.pKK]
should be committed by category coordinators in a dedicated branch-tag
(of the form geant4-XX-YY-patches_branch) created in CVS by the
release coordinator. A tag of the form category-name-VXX-WW-ZZ
has to be provided to STT as normal practice foresees, where ZZ
is the last increased number for that category in the previous
release series WW, and possibly mentioning that the tag is meant
for a patch to release XX.YY[.pKK].
Development and Beta Releases
Development releases of the source code are performed according to the
number of development and bug-fixes. A development release is made on a
regular basis at the end of each month for usage by Geant4 developers
and Collaborators. It includes code which passed all system tests
successfully but has not yet been validated or properly documented in
the user's manuals. It consists of a global CVS tag (reference tag),
including the categories' unit-test directories and system tests. It is
announced through the Geant4 developers mailing list by the release
coordinator, who also must provide detailed release notes, which are stored
in the CVS source repository.
The source code of development releases may also be publicly distributed
to registered beta testers, who can subscribe and download the code through
the Web. The source code (beta releases) will correspond to the one included
in a regular development release, provided exclusion of code explicitly
subject to publication rights by the authors.
3. Duties of a Category Coordinator
A category coordinator is responsible for:
- keeping his own test-release of Geant4 up-to-date with the latest
development release of the Toolkit and possible newer tags of
co-working categories (it might also be necessary to modify and tag
other categories at the same time),
- assuring that all unit tests for the detailed functionalities of the
category work properly and give the correct results,
- assuring that the category co-works properly with the other categories
in the current development release (i.e. it would be VERY useful and
appropriate to CHECK that the most relevant system integration tests
and examples work properly and give the correct results),
- performing the tests on AT LEAST TWO supported platforms,
- committing & tagging the category's code and related documentation
tree, after having properly updated the "History" file,
- announcing the tag to the STT (geant4-stt@cern.ch, STT) or
toggle to "Proposed for Testing" the corresponding tag entry in the
Bonsai Tag Database. The STT will then take care of testing the new
tag and, if approved, announce it to category coordinator. The
category coordinator should inform the STT of the following
information: the tag-name, the possible co-working categories tags,
a short description of the changes included in the tag and the TWO
supported platforms where the tests have been performed,
- informing the Documentation Coordinator of the updates to documents,
- promptly starting the process of fixing bugs or errors reported by
STT which affect his category after testing, and re-tagging and
re-announcing his category in time for the "bug-fix" release
phase,
- cooperating promptly with the STT during the "bug-fix" phase in
fixing those bugs/problems which may possibly affect his category,
by committing the fix (on the branch and/or also possibly on the HEAD
of the main CVS trunk) within 24 hours,
- providing to STT well tested tags based on branch-tags, to be
eventually included in a patch for an existing release.
Whenever a modification in a specific category involves the interface with
other categories (design changes), the category coordinator is responsible
for notifying the other category coordinators of the required changes, as
well as possibly applying them (pending approval of the other category
coordinators). In this special case, the category coordinator is also
responsible for the testing of the functionalities of all affected
categories AND the global tests and examples, in cooperation with several
category coordinators.
4. Duties of the Release Coordinator
The release coordinator is responsible for:
- building public and development releases of the toolkit on the reference
platforms/compilers agreed to by the STT. In detail, this means:
- compiling all the latest versions of the sub-domains approved by
the STT, verifying if they are indeed are consistent with each
other at the compiler level,
- compiling and linking all the acceptance tests (in
geant4/example/novice), verifying that the full code is
indeed consistent and builds correctly,
- running the acceptance tests, verifying if the code covered by the
tests is indeed consistent at run-time (automated process).
- writing the release notes for each public release and distributing
them,
- participating in the release of reference development tags (development
releases) and writing release notes for them to be distributed and
stored in the CVS source repository,
- participating in Q/A activities during the release phase, meant to
identify problems of dynamic memory management in selected system
tests.
The following are NOT the tasks of the release coordinator:
- fixing bugs (though, can collaborate or point to a solution),
- porting of the code to new architecures,
- maintaining the overall infrastructure (i.e. GNUmakefiles and related
directory hierarchy),
- in case of the failure of a system test, examining 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.
5. Releases & Tag formats
The following rules apply to the global release tags:
|
