GEANT4 User Support Process

Definition: The provision of help and analysis of code-related problems, 
            the consultancy, and the enhancement requests, as well as the
            investigation of anomalous results, are defined as the GEANT4
            "User Support".


 
The User Support relative to the GEANT4 software is performed by the GEANT4
collaboration, a world-wide collaboration of experiments, laboratories and 
institutes, which distribute amongst themselves the user support 
responsibilities and the maintenance of the various domains of the GEANT4 
software (as described in the GEANT4 Memorandum of Understanding).

The GEANT4 software has been developed by a world-wide R&D project of about 100 scientists
from over 40 institutions and laboratories participating in more than 10 experiments in 
Europe, Russia, Japan, Canada and the United States.
Geant4 exploits advanced software engineering techniques and Object Oriented technology to 
make possible the distributed software design and development in the world-wide 
collaboration. 
Many specialised working groups have been responsible for fields as divers as physics, 
geometrical modelling, visualisation, event generation and user interfaces.
A major advantage of this distributed approach is the exploitation of the expertise and 
knowledge of scientists all over the world. Moreover, the consequent distribution of
responsibilities requires the maintenance of modular software and clear definition of
interfaces between components.

A distributed User Support model was driven naturally by the existing distribution of
expertise and manpower across the experiments, laboratories and institutes which have
contributed to create and mantain GEANT4. 
This model offers major advantages over a traditional central support:
- A larger number of people is now performing the support, and always on the domain of 
  their competence or even on the code they developed themselves.
- A larger number of contact/reference points for the users are now available, avoiding 
  the channelling of all problems through the same support people and thus improving
  efficiency.

In order to exploit those advantages, an adequate structure is needed to filter, analyse, 
dispatch, or prioritise the users' requests, and also to provide the user with a direct
interface to which one can refer without knowing the details of the GEANT4 User Support
mechanism.
The needed structure is provided by the GEANT4 Technical Steering Board and the GEANT4
Working Groups.

The Technical Steering Board:
The TSB is the forum where technical matters (software and physics), users requests, and 
further developments are discussed, prioritised, and decided. 
Each laboratory, experiment or institute signing the GEANT4 MoU (representing users
communities), as well as each GEANT4 Working Group (representing technical expertise), 
has one representative in the TSB.
The representative of each laboratory, experiment, and institute in the TSB is the contact
and reference person for the user community represented by his/her laboratory, experiment,
or institute. Those TSB representatives have the knowledge needed and the possibility to
contact the proper Working Group to address the requests of the users they represent. 


The Working Groups:
The Working Groups tasks are assigned by the TSB. 
The Working Groups perform the work necessary in each GEANT4 domain:
Run&Events, Tracking, Particles, Processes&Materials, E.M. Physics, Hadronic Physics,
Geometry&Transport, Detector Response, Visualisation, User&Categories Interfaces, 
Testing&QA, Software Management, Documentation Management. 
The Working Groups co-ordinators are initially selected among the current RD44 working 
group co-ordinators of the GEANT4 domains and activities in order to ensure continuity.

The TSB and the Working Groups perform the full User Support process.

The provision of help related to the documentation and analysis of code related problems, 
such as bugs and fixes, is guaranteed to the user in two ways, and in addition a modern
problem tracking procedure is applied.
If a bug is found in any GEANT4 source file, the user is able to fill a web form 
which will automatically route the problem report to the Coordinator of the Working Group
responsible for the domain to which the given file belongs; the problem will be classified
in a web-based data-base where it is possible to consult its status and evolution; 
the user will be acknowledged of the reception of his report within 24 hours.
Alternatively, the user can contact his representative in the TSB, who will take care to
forward or discuss the problem reported with the responsible working group coordinator,
which will then allow the same procedure as above. The ultimate responsibility to 
accept or implement a fix belongs to the Working Group Coordinators. 
Every fix is implemented in a cvs branch and is thus available in no time, on top of the 
reference GEANT4 release, to any interested user. In addition, the branching system of
cvs allows the user to load any desired selection of fixes to be applied on top of the
reference release.

The consultancy requested by the users before finding any problem represent cases where
a human interface is necessary. The same is true for the investigation of anomalous
results, such as when the program runs but the user suspects that the physics results
are not correct. In these cases, each user is supposed to refer to his/her representative
in the GEANT4 TSB, who will proceed to contact the people responsible for the affected
GEANT4 domains.
 
The users' requests for enhancements, as well as any modification involving interfaces
between multiple GEANT4 domains, will be discussed, prioritised and decided by 
the GEANT4 TSB. In the same style, the TSB is responsible to take decisions such as
triggering a GEANT4 release. In this case, a formal procedure is applied:
- The Testing&QA Working Group performs the system testing and the acceptance testing.
- The Software Management Group is then responsible to tag, release and distribute the new
  GEANT4 version.
- The Documentation Management Group is responsible to release the updated users manuals,
  reference manuals, and other public documents such as the URD.



                         GEANT4 User Support Use Cases

Provision of help (on the documentation or on where to find information)

G4USC-1  Where can I find the manual, both in hypertext and printable format
         (such as Postscript) ?
         On the web it is possible to access 6 manuals, including an 
         Introduction, an Installation Guide, two User Manuals (for different 
         levels of expertise), a Physics Reference and a Software Reference 
         manuals. The address is:
         http://wwwinfo.cern.ch/asd/geant/geant4.html .

G4USC-2  Where can I find the manuals already printed ?
         In each laboratory and institute participating to the GEANT4 
         collaboration copies of the manuals will be available (e.g. at the 
         Users Help Offices).

G4USC-3  If I work in an experiment participating to the GEANT4 collaboration,
         who should I contact to ask for some first aid help ? 
         Each experiment participating to GEANT4 has a G4 Technical Board 
         Representative who is the person to be contacted for getting first aid
         help within his domain of expertise and information.

G4USC-4  If I work in an experiment not participating to the GEANT4 
         collaboration, who should I contact to ask for some first aid help ?
         You should select an institute or laboratory involved in your 
         experiment, and at the same time participating to GEANT4, and contact 
         its G4 Technical Board Representative, who will offer information and first 
         aid help within his domain of expertise (to an extent that is at the discretion 
         of his laboratory or institute) on best-effort basis.  



Analysis of code-related problems

G4USC-5  If I find a bug, identifying the file affected, who should be informed?
         A WWW interface available from the GEANT4 web will forward the bug 
         report to the responsible person for the GEANT4 domain to which the 
         affected file belongs. The responsible person is the G4 Working Group 
         Coordinator of the given domain, and he is a member of a laboratory or 
         experiment participating to the GEANT4 collaboration.

G4USC-6  If I find a bug, how can I check if it has been fixed already, 
         or what is its status ?
         The GEANT4 web makes available a data-base of open Incident Reports, 
         tagging the ones already fixed and showing their status. In addition, 
         an acknowledgement will be sent. 

G4USC-7  If I work in an experiment or institute participating to the GEANT4 
         collaboration, how can I require that a bug be fixed in a time useful 
         for my needs ?
         The G4 Technical Board Representative of your experiment or institute 
         is responsible to discuss with the Technical Representative of the 
         experiment, laboratory, or institute responsible for the domain where 
         the bug was found. Unless there are no conflicting priorities, the fix
         is implemented in the shortest possible time and made available in a 
         branch of the code repository.
         Otherwise, the issue is addressed at the GEANT4 Technical Steering 
         Board, which is the forum where technical matters are discussed and 
         prioritised.

G4USC-8  If I work in an experiment or institute not participating to the GEANT4
         collaboration, how can I require that a bug be fixed in a useful time 
         for me ?
         You cannot require that a bug will be fixed in a given time. The 
         priority of the needed work will be decided by the GEANT4 Technical 
         Steering Board according to the interest of the represented 
         experiments, institutes and laboratories.

G4USC-9  If I find a fix, who should be informed ?
         The same procedure as for reporting bugs should be followed, including
         the fix in the bug report.

G4USC-10 If I propose a fix, who is responsible to approve it ?
         The G4 Technical Board Representative of the experiment, laboratory,
         or institute responsible for the domain where the fix has to be applied
         and the relative Working Group Coordinator are responsible to decide. 
         If the fix affects more than a domain, then the matter has to be 
         addressed at the G4 Technical Steering Board.

G4USC-11 How much time it will take to implement my fix ?
         The timescale to implement a proposed fix is subject to the same 
         conditions as for the fixes associated to bug reports.



Consultancy (requests for expert reccomendations before finding problems)
 
G4USC-12 If I am working in an experiment participating to the GEANT4 
         collaboration, and I need to discuss technical matters specific to my 
         experiment's simulation application, who can I contact?
         The G4 Technical Board Representatives of your experiment and of the 
         laboratory or institute where you are working will be available to 
         provide consultancy within his domain of expertise.

G4USC-13 If I am working in an experiment not participating to the GEANT4 
         collaboration, and I need to discuss technical matters specific to my 
         experiment's simulation application, who can I contact?
         You should select an institute or laboratory involved in your 
         experiment, and at the same time participating to GEANT4, and contact 
         its G4 Technical Board Representative, who will offer consultancy within his
         domain of expertise (to an extent that is at the discretion of each institute
         or laboratory participating to the GEANT4 collaboration) on best effort basis. 



Enhancements requests

G4USC-14 To whom I could send a proposal of a new requirement for an improvement
         in functionality?
         Any new requirement will be discussed at the GEANT4 Technical
         Steering Board.
         You should contact the G4 Technical Board Representative of your 
         experiment, institute, or laboratory to pose the given requirement to 
         the GEANT4 Technical Steering Board.

G4USC-15 How can I get an enhancement into the GEANT4 code 
         independently from the agreement of the other experiments, 
         laboratories, or institutes participating in the GEANT4 collaboration ?
         A new requirement will trigger a cycle of analysis, design, 
         implementation, testing and documentation, that can involve 
         responsibilities of different laboratories and experiments. In all 
         cases, any new software or enhancements which will become a part of 
         GEANT4 has to be agreed by the GEANT4 Technical Steering Board, which 
         has also to ensure the consistency of the whole product.

G4USC-16 What is the timescale to get implemented an enhancement in the 
         software ?
         If the request is produced by an experiment/laboratory/institute 
         participating to the GEANT4 collaboration, the timescale is the one 
         determined by the procedure explained above. Otherwise, it might be 
         longer because it will be analysed after the requests and proposals 
         coming from members of the GEANT4 collaboration.
          


Investigation of anomalous results
 
G4USC-17  I get a result I can't understand, what can I do?
          If your GEANT4 application runs but you suspect the results produced 
          are wrong, you have to inform the G4 Technical Board Representative of
          your experiment or institute. He will then be responsible to contact 
          the G4 Working Group Coordinator or the G4 Technical Board 
          Representative of the domain to which the anomalous results refer. 
          They will then investigate the problem as soon as possible, according
          to the priorities set by the GEANT4 Technical Steering Board.

G4USC-18  How can I access a debugging environment?
          If you are working in an experiment/institute/laboratory participating
          to the GEANT4 collaboration, you can ask to access the GEANT4 servers
          (if any) or accounts available in your experiment/institute/laboratory
          (including the access to libraries compiled in debug mode for various 
          platforms).
 
 

Miscellaneous

G4USC-19 Do I need to send emails to a general mailing list ?
         No, the GEANT4 user support is made of the activities listed above,
         and for each activity there is a dedicated interface as explained 
         above.

G4USC-20 Is there a regular user meeting which I should attend ?
         The GEANT4 user support is distributed between different laboratories, 
         institutes and experiments, so there will be only a global GEANT4 
         workshop per year when all the responsible people of the GEANT4 domains
         will meet together with users' representatives and the members of the 
         GEANT4 collaboration. However, there are regular GEANT4 users meetings 
         within each experiment participating to the GEANT4 collaboration, which
         can be attended to inform and discuss with the respective G4 Technical 
         Board Representative.

G4USC-21 To whom should I refer to give feedback on the GEANT4 user support or 
         propose improvements for the user support ?
         You should contact the GEANT4 Collaboration Board Representative of 
         your experiment, institute, or laboratory.