Tag and 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

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, 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.

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:

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.

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 public release is a collection of all announced merge requests approved by the STT. Every established public 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, etc…) is also packaged.

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 Master of the source repository.

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 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) 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 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 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.

Duties of a Category Coordinator

A category coordinator is responsible for:

keeping his own test-release of Geant4 up-to-date with the current development version of the Toolkit (Master branch of the GitLab code repository),
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 version (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 & creating a Merge Request for the category’s code and related documentation tree, after having properly updated the “History” file with appropriate “tag-ID”,
the Merge Request will automatically undergo Continuous testing. The STT shifter will then take care of testing the new MR and report about 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 and a short description of the changes included in the tag,
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; submit corrections to the related MR to re-trigger testing,
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,
submit well tested 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 (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 category coordinators.

Detailed information about the testing shifter procedures can be found in GitLab.

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 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 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 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 (though, can collaborate or point to a solution):

fixing bugs,
porting of the code to new architectures,
maintaining the overall infrastructure (i.e. Makefiles/CMake scrips 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 should be applied. In that case, a pre-packaging preceding 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 repository directory or module.

Releases & Tag formats

The following rules apply to the release tags:

A public release is tagged with the following tag format:
```
 geant4-XX-YY
```
where:
- XX identifies the major release version number, and is incremented sequentially. A major release includes new development in the kernel code, i.e. new features and changes to interfaces. It may therefore require modification and porting of the user code,
- YY identifies the minor release version number; it is incremented sequentially and reset at every new major release. A minor release must assure full compatibility with previous minor releases of the same trunk. A public release tag should not include the system tests directory and the Categories’ unit tests directories.
A development reference tag is identified by a tag of this format:
```
 geant4-XX-YY-ref-ZZ
```
where: A reference tag for development collects all announced category tags from developers which passed the System Testing procedure and therefore have been accepted as valid tags by the STT. It includes either bug-fixes or new development. It is made available only to developers and collaborators in order to allow them to synchronize their development with the evolution of the toolkit.
- XX-YY refers to the latest minor public release,
- ZZ is the development reference release number, which is incremented sequentially along development and reset at every new major/minor release.
A development beta tag is identified by a tag of this format:
```
 geant4-XX-YY-beta-ZZ
```
where: A beta tag should not include the system tests directory and the categories’ unit tests directories.
- XX-YY refers to the latest minor public release
- ZZ is the development reference release number as for the corresponding reference tag.
A development candidate tag is identified by a tag of this format:
```
 geant4-XX-YY-cand-ZZ
```
where: A candidate tag may be made available by the STT team to beta-testers with the purpose of allowing further testing on the category tags it collects.
- XX-YY refers to the future public release
- ZZ is the development candidate release number, which is incremented sequentially along development and reset at every new major/minor release. It usually refers to the tag which is candidate to become the next reference tag for development, or the next public release.
A release patch tag is identified by tags of this format:
```
 geant4-XX-YY-patch-ZZ
```
where: A patch tag should not include the system tests directory and the categories’ unit tests directories.
- XX-YY refers to the latest minor public release
- ZZ is the patch release number, which is incremented sequentially and reset at every new major/minor release.
A release branch tag for patches is identified by tags of this format:
```
 geant4-XX-YY_patches
```
where:
- XX and YY refer to the major or minor public release, which is going to be patched.
- the optional branch_root tag identifies the original ancestor from which the branch has been generated.
A generic category tag is identified by tags of this format:
```
 category-name-VXX-YY-ZZ
```
where: There is no tag policy defined or imposed on category coordinators concerning the development inside each category. A category coordinator is free to adopt the policy best suited to the development of the domain for which he is responsible. However, official category tags which will be announced to the STT for testing, should be compliant with the above format and policy.
- category-name refers to the real identifier for the category or sub-category,
- VXX-YY refers to the latest public release (major or minor),
- ZZ is the development reference release number, which is incremented sequentially along development and reset at every new major/minor release,
- the tag refers to the corresponding directory or tree of directories in the repository, and NOT to just a part of it!

Additional information about the release procedure can be also found in GitLab.