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.
- The GEANT4 Release Policy
- Duties of a Category Coordinator
- Duties of the Release Coordinator
- Releases & Tag Formats
Geant4 is composed of several class categories (or sub-domains or components).
Each sub-domain is associated with a directory in the source repository, which
in turn may be composed of sub-directories.
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 or main TRUNK 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 and integration tests (i.e. system tests are 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 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 an integrated subset of those covered by the system integration tests.
Finally, each system test and example must have a reference-input and a
reference-output. The result of each system 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 system 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 for assuring the correct functioning.
2. The GEANT4 Release Policy
A general release of the Geant4 Toolkit has to be performed at the dates
established by the milestones set for the Collaboration and formalised by the
Steering Board (SB). A general release might be major or minor,
according to the following specification:
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:
- 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
after approval of the SB, when a reasonable number of updates are
considered suitable to be distributed to the public.
A public release is a collection of all announced category tags approved
by the STT. Every established public release consists of a bug-fix phase
followed by a release phase:
- the flow of new development and critical updates, and
- the established Working Group milestones for code delivery.
During the entire release period (7 weeks), bug-fixes may also take place
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 or main TRUNK of the source repository.
- 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
- 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, etc...) is also packaged.
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
The source code, release notes, data sets and binary libraries for the
supported platforms/compilers are made available for downloading from the 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 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 a 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 with supervision by the release
coordinator in a dedicated branch of the source repository (with tag of the
form geant4-XX-YY-patches_branch) created 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
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 tag (reference tag) in the
source repository, 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 source repository as well.
Occasionally, the source code of development releases may also be publicly
distributed to public and registered beta testers, who can 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:
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 (in agreement with 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 system tests and examples, in cooperation with several
- 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 (email@example.com, STT) by
toggling to "Proposed" for Testing the corresponding tag entry in the
Tags Database. The STT will then take care of testing the new
tag and announce the result to the 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 eventually
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 which may be
reported by STT for his category after testing; re-tagging and
re-announcing the new tag to STT,
- 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 within 24 hours,
- providing to STT well tested tags, to be eventually included in a
patch for an existing release.
4. Duties of the Release Coordinator
The release coordinator is responsible for:
The following are NOT the tasks of the release coordinator (though, can
collaborate or point to a solution):
- 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 consistent with each
other at the compiler level,
- compiling and linking all the basic 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).
- drafting the release notes for each public release and patch and
- participating in the release of reference development tags (development
releases) and writing release notes for them to be distributed and
stored in the source repository,
- participating in Q/A activities during the release phase, meant to
identify problems of dynamic memory management in selected system
The release coordinator should be involved when major modifications to the
infrastructure of the toolkit should be applied. In that case, a pre-packaging
preceeding the re-organisation should be applied and either one of the
following two actions should be performed:
- fixing bugs,
- porting of the code to new architecures,
- maintaining the overall infrastructure (i.e. Makefiles and related
- 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.
- stop development for a reasonable amount of time (few hours) to allow
the migration, or
- create a brand NEW repository directory or module.
5. Releases & Tag formats
The following rules apply to the release tags: