Architecture

The architecture is shown on the following picture:

You will be using two tools.

• g4svn - manual here https://twiki.cern.ch/twiki/bin/view/Main/G4SVNDoc
• geant4tags - bonsai replacement, described in this manual.

The Geant4 SVN repository is hosted by CERN SVN Service. There are many SVN servers hosting many projects accessible (for authorized user) under:

svn+ssh://svn.cern.ch/reps/PROJECT_NAME

as Geant4 repository is named geant4, it is available under svn+ssh://svn.cern.ch/reps/geant4.

One of the feature of the SVN repositories are hook programs. These programs are run by SVN repository when certain action happens. They usually invoke other programs, provided by the repository administrator, which can be written in any programming language. Examples of the hooks:

• pre-commit - is being invoked before commit. They usually check if SVN repository should allow the user to commit changes.
• post-commit - is being invoked after commit - They can for example send an e-mail with some information about the commit.
• there are many more hooks

Geant4 SVN repository provides pre-commit hook which:

• checks if before tagging, changes were committed to the trunk,
• implements sticky tags - once the tag was created, one should not be able to change it,
• stores information about the tag in the geant4tags web application database.

If pre-commit hook finds any problem, it sends error message to the user and blocks the commit.

On Your machine, You will have some Geant4 working copy and a helper tool g4svn. In general, You will be using native SVN commands but for some tasks (requiring typing longer commands) g4svn can come handy. One of this tasks is tagging. In SVN there is no special functionality implemented for tagging. Tagging is done by copying progress to a special place in the repository. For example, when tagging event category (geant4/source/event), svn command would be (invoked in geant4/source/event):

#Tagging event with the tag name event-VXX-YY-ZZ
svn copy . svn+ssh://svn.cern.ch/reps/geant4/tags/geant4/source/event/_symbols/event-VXX-YY-ZZ -m "Creating tag event-VXX-YY-ZZ"

Command copies content of the current directory into tags/geant4/source/event/_symbols/event-VXX-YY-ZZ directory in the Geant4 SVN repository - more information about tagging in Geant4 SVN repository and repository layout can be found in the g4svn tool documentation https://twiki.cern.ch/twiki/bin/view/Main/G4SVNDoc.

In progress of creating a tag, the information about it is being read by pre-commit SVN hook. It stores the tag information in the geant4tags web application database which is located on some machine at CERN.

Another machine serves the geant4tags web application. You can access it under https://sftweb.cern.ch/geant4/geant4tags. Note that You have be to logged in. You can login by clicking a blue "Login" anchor in the top right corner of the web page. Then, a new option "Web Applications" will appear in the main menu. One of the sub-options is "Geant4 Tags".

General information

geant4tags is one of the two tools that Geant4 developer will be using. It is a bonsai replacement, and it's main purpose is to mange the tags.

In progress of creating a tag, the information about the tag is being read by pre-commit SVN hook. It stores the information about the tag in the geant4tags web application database. Tag appear immediately on the web page because it is stored just before the g4svn tool exits.

In general, You get the same information as in the Bonsai:

• Creation date,
• User who created the tag,
• Category which was tagged,
• Name,
• Information about the bugfix,
• Tag status,
• Description,
• Sentence (why the tag was rejected).

Something new is Development line (the last column in tags table). Development line represents some development time interval – from one global tag to another. New system enables to collect (and manage) tags which can go with concurrent development lines. It means that tags do not have to always go together with the most recent global tag. When creating a patch, some tags will be on top of some older global tag and thus creates different development line. Development line consists of a global tag, and assigned tags. Usually, development line is named as a global tag on top of which tags are being added. However, for patches, development line will be named different.

Browser compatibility

In general, geant4tags should work on any modern web browser. It uses modern libraries to provide the most of functionality.

If You have accessed geant4tags and received something similar to (example on the Konqueror web browser):

and Your web browser claims that it has loaded the page, then Your web browser is unfortunately unsupported.

It is recommended to use either Google Chrom , Opera or Firefox (version 4 and grater - by the time of writing this manual, Firefox 4 was in beta stage but geant4tags worked well).

geant4tags manipulates (a lot) on the parts of the page - hiding table, showing table, removing table, removing rows, sorting rows ... This is the best supported by Chrome. In second place - Opera. Firefox versions lower then 4 are slow. Example: Chrome and Opera are usually 15 times faster then Firefox when sorting the tags table.

Internet Explorer (currently), is the worst so please try to use different web browser. If You are using Internet Explorer, please be patient when doing almost any operation.

Functions

There are eleven places where You can interact with geant4tags web application, shown below:

In the following points You can find short description of those ten places.

1. Marking tags

geant4tags web application enables You to change the status of many tags at once. Every tag data row has in the first column a checkbox. You can tick those checkboxes to mark a group of tags which status You want to change. Please note, that You can only change status of many tags if they have the same status. Moreover, You can only change the internal and proposed status.

When You are done with marking tags, You can change their status by clicking Change status button [5] . You can also clear marked tags by clicking Clear marked button [6].

2. Sorting table

You can sort the table by clicking the headers of the table. You can also multiple sort by holding the SHIFT key while clicking the headers.

3. Querying the database of the tags

When You click Query button [3], a pop up form will be show where You can provide the criteria of a query to the database of tags:

In Tag, Path and Who text field You can either type the value or You can type ALL or leave empty if You don't want to take any of this criteria.

Some web browsers have problem with displaying to many tags. You can limit the result by providing value in the LIMIT textfield.

4. Refreshing the result of query

After clicking the Refresh button [4], geant4tags will take the criteria form the query form (button 5), and request tags from the database.

5. Change tags status

You can only change tag status if it has either status internal or proposed. After marking some tags (see Point 1) You can click Change status button [5] to change the status of many tags at once. Please note, that You can change selected tag status if they have the same status. geant4tags will open different pop up forms depending on what status do selected tags have.

Changing from internal status.

If You decide to change the status of set of internal tags, then the following pop up will be shown:

On top of the form there are names of the tags You are about to change. Later, new status, which can be only proposed. Then, You have description field set. Geant4tags has integrated ckeditor (http://ckeditor.com/). It allows You to put rich text as a description of a tag. Currently, supported options are:

• Bold
• Italic
• Underline
• Strike
• Ordered list
• Unordered list

By default, ckeditor is in Source mode (Source button toggled), this means that the buttons for the rich text edition are disabled and the text will be a plain text (as long as You won't put any html tags). If You want to put some rich text into the tag description, please press the Source button to change the mode.

The last field set concerns bugfix. By default, the bugfix checkbox is unchecked. If tag contains a bugfix, this checkbox should be checked. Optionally You can provide a bugfix number (the bugzilla problem number).

Changing from proposed status.

Currently, You can also change the tag status from proposed to rejected. In the sentence fieldset You can provide reason why You reject the tag.

6. Clear marked tags

You can clear marked tags by clicking button Clear marked [6].

7. Bugfix

If the tag has fixed a bug with number, then in Bugfix column this number will be shown and You can click it to be redirected to bugzilla web page, to specified problem number.

8. Change status of a single tag and access information about accepted tags on top off certain global tag

If You want to change status of a single tag, You can just click the Status cell of a tag row. It is the same as marking this tag via Mark cell [1] and then clicking Change status button [5].

You can see what accepted tags have been included on top of some global tag by clicking the status cell of a global tag. A pop up dialog will be shown similar to:

9. Viewing the tag description.

Normally, the description is truncated so that the tags table remain neat and readable. If You want to see the full description, rollover the mouse cursor on the description cell and a pop up bubble will be shown.

10. Viewing the tag sentence.

See point 9, as sentence column behavior is the same.

11. Accessing the full interface

geant4tags has two version. The one, described here, enables doing the most common for Geant4 developer tasks, There is also a admin version which You can access by clicking Full interface button. Please be careful when using the admin version as Your action can effect the Geant4 testing procedures.

Problems, strange behaviour

Tags table does not contain any tags or not the one that I wanted

geant4tags updates the table of tags when You:

• Query tags via Query button,
• Refresh the table via Refresh button,
• Change the status of a set of tags,

geant4tags ALWAYS takes the query criteria from the query form accessible under the Query button. If You receive unexpected tags table, please check the query form if it has the proper criteria. For example, these actions would lead to empty tags table:

1. You click Query button [3]
2. In Date field set. You choose option "In the last" and then put "blablabla" as a value.
3. You hit "Query" button. Input "blablabla" fill become red as You have typed string not integer.
4. You hit "Close" button. Bad input is still unchanged.
5. You change the status of some tag. Tags table is being refreshed but because there was not appropriate data provided in the query form, tags table will be empty,

This behaviour maybe changed is some near future but for now, no reasonable action was figured out.

The ckeditor (rich text editor) for the description text area behaves strange

The ckeditor is a quite mature project and widely used. Still, it has some problem and they are strongly related to the web browser You are using. Despite the flaws, it really is usable and most of the problems can be workaround.

For example:

• on some Google Chrom web browser. If You cannot toggle the Bold (or similar) button, You can select, with Your mouse, some text and then hit Bold.
• on some Internet Explorer web browsers. If You can get focus on the editor (put any chars into the editor), hit Source button. You should be now able to edit.

If You encounter any problems with the ckeditor and at the first look it's impossible to work with it then the best advice is ... keep trying! Otherwise, You still have button "Switch to plain text editor" which will shut down ckeditor and You will have access to normal textarea.

Everything disappears, and an error message is shown where the buttons and table should be

geant4tags receive an error from the server. The error should be one of the following:

• Not logged in

It usually hapens when You were using the geant4tags then left the tab in Your web browser, with this application, opened for some longer time. Your sessions has expired and You have to login once again.

• Bad URL

Please check if You haven't typed any extra chars to the URL where the geant4tags are, or access the application once again by going to Web Applications >> Geant4 Tags in the main menu. If You have typed a proper URL address then a problem is on the server side.

• Bad Gateway

This error appears rarely on some version of the Firefox web browser and on the admin version of the geant4tags. It should not happen to You, but if it does, please use different web browser.

• Other

Currently, no other errors have been discovered but if any would appear, try to use different web browser.