NuWa Trac

Glossary

ticket	defect OR enhancement request
Trac Instance	installed Trac web application associated with an SVN repository
workflow	a sequence of states thru which tickets pass

Nuwa Trac Login and Preferences

Prior to login the top line tabs of Trac will be almost empty, only allowing access to the front page and links into other pages will result in error messages featuring 404 not allowed. Access the full functionality using the Login link near the top right.

To be informed of status changes to tickets your create or close or build/test failures associated with your commits you must associate an email address with your Trac account using the preferences link at the top right.

Tickets

Should you create a new ticket ?

First search for a pre-existing ticket that matches your intended one, using the search box at top right of the dybsvn Trac instance. If you do not find a matching ticket click the New Ticket tab available at the top of every dybsvn Trac page.

If in doubt create the ticket anyhow, if it is a duplicate it can easily be flagged as such.

Fields To Fill

Short summary	provide the bottom line error in full (by copy and paste) , searchability is more important than readability
Type	defect/enhancement/task
Full description	Mention the command you were running and any peculiarities of your installation, also mention your platform. Provide at least the last 10 lines or so of traceback up to and including the bottom line error. See below for details of creating good descriptions
Priority	blocker/critical/major/minor/trivial
Milestone	assign the ticket to a milestone (optional ... usually leave this to management )
Component	sub-component of the NuWa software concerned. See below list of components
Version	the version of the software in use (eg trunk )
Keywords	comma or space separated list of keywords eg Linux,Ubuntu,Zlib,Prerequisite, see below for Keyword guidelines
Assign To	username of the person tasked to handle this issue (optional ... usually leave this to management )
CC	(optional ... additional email address to be notified of status changes to this ticket )

Example Image of Ticket Creation

Ticket Type

Provides categorization of the ticket:

Defect	a bug, anything that does not work as expected
Enhancement	a new feature or an improvement over an existing one
Task	everything else, something that needs to be done

Priority Classification

Priority, for asserting the importance of a ticket

blocker	basic functionality is not available until this is fixed
critical	severe loss of data due to the defect or highly needed enhancement
major	defect with major impact / big enhancement
minor	defect with minor impact / small enhancement
trivial	defect with little or no impact / cosmetic enhancement

NuWa components

owner		name
offline		Infrastructure /
bv		Infrastructure / BNL Wikis
cetull		Infrastructure / Mailing Lists
mwang		Infrastructure / Official IHEP Web Site
tianxc		Infrastructure / SVN
blyth		Infrastructure / Trac
offline		Installation /
bv		Installation / Debian
dandwyer	Installation / Mac OS X
patton		Installation / Scientific Linux
offline		Unclassified /
bv		dybgaudi//
patton		dybgaudi//DataModel
offline		dybgaudi//Database
bv		dybgaudi//Detector
offline		dybgaudi//Documentation
blyth		dybgaudi//DybTest
offline		dybgaudi//Generators
bv		dybgaudi//RootIO
offline		dybgaudi//Simulation
bv		dybgaudi//Simulation/DetSim
bseilhan	dybgaudi//Simulation/ElecSim
wangzhe		dybgaudi//Simulation/Fifteen
bv		dybgaudi//Simulation/GenTools
wangzhe		dybgaudi//Simulation/Historian
bseilhan	dybgaudi//Simulation/ReadoutSim
bseilhan	dybgaudi//Simulation/TrigSim
offline		dybgaudi//Validation
kevin		dybgaudi//Validation/DetSimValidation
offline		gaudi//
offline		lcgcmt//
offline		lhcb//

The dynamic list is at {10} The components are comprised :

• name ( free-form, but most are derived from repository paths )
• owner ( corresponding to the SVN username , which via Trac preferences is associated to an email address )

They provide a classification of tickets, that is used for automated email notification to the relevant owners.

automated component updates

To reduce the maintenance burden of maintaining a long list of paths and owners, the directories to be promoted to components are identified by the setting of SVN owner properties on directories in the repository (these properties are visible in the web interface) :

cd dybgaudi/Simulation
svn propset owner bv GenTools
> property 'owner' set on 'GenTools'
svn propget owner GenTools
> bv
svn ci -m "set properties for the autocomponent script "

The properties are propagated into components via the autocomponent script that is manually run on the server. The result of property changes is the creation/updating/deletion of the components, in the above case components are created/edited :

• dybsvn:/dybgaudi/trunk/Simulation/GenTools -- owner set to bv
• dybsvn:/dybgaudi/trunk/Simulation/ -- owner set to the default offline (unless overridden by another propset )
• dybsvn:/dybgaudi/trunk/ -- owner set to the default offline

The Trac preferences for the SVN user offline allows the setting of an email address associated with the additional components.

For further details (only administrators need know more) see the script hosted at NTU :

• http://dayabay.phys.ntu.edu.tw/tracs/env/browser/trunk/trac/autocomp

Writing a good description

Good descriptions for a problem report are the ones that make it easy for the developers to understand and/or reproduce the problem. To that end, it's usually necessary to give the following information:

• How To Reproduce: describe what you were doing when the problem happened such that someone following your instructions can reproduce the problem. The fewer the steps and shorter the time needed to reproduce the issue the more attention developers will give to finding a solution so attempt to isolate the issue if you can.

• backtrace: if you have one, append it at the end of the description, enclosed in a {{{ ... }}} block, creating a code block.

Note the description can use use the full range of Trac wikitext formatting and linking facilities. See the front page (http://dayabay.ihep.ac.cn/tracs/dybsvn) of the dybsvn Trac instance for examples of linking to revisions, docdb documents, wiki pages, other tickets etc..

Good Keywords

Assigning appropriate keywords to your tickets will facilitate rapid finding of issues and finding related issues.

To assign good keywords check the list of keywords (Tag Cloud) on the front page (http://dayabay.ihep.ac.cn/tracs/dybsvn) for tags or keywords that are appropriate to your issue and then re-use those with the same spelling and capitalization. Using multiple short keywords (delimited by spaces) is encouraged. When creating new keywords follow the capitalization conventions of the pre-existing keywords.

Trac Wiki Text basics

Code blocks

Code blocks, useful for stack traces, are defined using three curly brackets :

{{{
  def HelloWorld():
      print "Hello World"
}}}

Display:

 def HelloWorld():
     print "Hello World"

Details on wiki formatting

• http://trac.edgewall.org/wiki/WikiFormatting

Diff blocks

Present a unified diff with the wikitext :

{{{
#!diff
Index: bitten/admin.py
===================================================================
--- bitten/admin.py	(revision 547)
+++ bitten/admin.py	(working copy)
@@ -235,6 +235,22 @@
             config.delete(db=db)
         db.commit()
 
+
+    def _resolve_recipe(self, recipe_xml , authname ):

}}}

Linking using url prefixes

Wikitext like :

docdb:101

can be turned into a link by setting up URL prefixes by editing a wiki page, which associates docdb with the required URL.

• dybsvn:wiki:InterMapTxt

Links to other tickets can be made using hash followed by the ticket number, eg

#1

Details on linking

• http://trac.edgewall.org/wiki/TracLinks

Ticket Workflow

From Trac 0.11 the states thru which tickets pass is configurable, depending on the workflow in use, the basic one is intended to be used.

• http://trac.edgewall.org/wiki/TracWorkflow

Viewing Tickets

Reports

Users with appropriate permissions can create named customized reports by tweaking an SQL statement

• http://trac.edgewall.org/wiki/TracReports

after which additional entries will appear in the Available Reports list obtained from the View Tickets link.

Links to these reports can be made using wikitext, eg for report 6

{6}

This wikitext can be entered into the search box at top right to access the report. Note that milestone descriptions are in wikitext, hence can contain links to such customized reports.

Queries

An alternative to reports is to create a query interactively , by choosing Custom Query at the top right while viewing Available Reports. The queries can also be stored in wikitext form.

• http://trac.edgewall.org/wiki/TracQuery