Before you use Yaktrack to track any issues at all, you must create a repository. Using the yaktrack.py create-repository command creates a standard (mostly empty) repository structure in the current directory. If a default repository exists (under the default-repository subdirectory of the Yaktrack distribution), its contents will be copied into the new repository, with all templates, etc. intact. This allows a system administrator to create a "standard" repository that will be copied into all new repositories, ensuring that all projects in an organization use the same templates, etc.
To use this command, enter the directory in which you would like the repository located, and invoke yaktrack with the command yaktrack.py create-repository. Yaktrack will create the repository in that directory, and then list its current contents so that you can verify its existence:
[vputz@yak_prime temp]$ ../yaktrack.py create-repository Attempting to copy default repository... Repository Contents yaktrack-repository: templates issues awaiting-review yaktrack-options yaktrack-repository/templates: defect yaktrack-repository/issues: yaktrack-repository/awaiting-review: yaktrack-repository/yaktrack-options: [vputz@yak_prime temp]$ |
Here, the default repository did indeed have some contents, and you can see that in the yaktrack-repository/templates directory, the file defect reflects the existence of a defect template.
Once the repository has been constructed, you will be able to use the other common yaktrack commands, such as submitting an issue, filing a new issue, editing or listing issues, and querying issues.
The submit command is one of the most used commands in Yaktrack -- indeed, probably the most used except for the edit command. The submit command allows the user to submit a new issue; you must provide a template name to use with the submission. In the following example, the user is submitting a new defect:
[vputz@yak_prime temp]$ ../yaktrack.py submit defect defect /home/vputz/projects/class/yaktrack/src/temp/yaktrack-repository Attribute: (defect:confidential) 1 . yes 2 . no [ 2 ] >> 2 Attribute: (defect:test) Old/Default contents: test_value [return keeps contents] >> test Text Contents: submitterid Old/Default contents: [return keeps contents] >> vputz Text Contents: originator Old/Default contents: [return keeps contents] >> Winged Yak Productions testing facility Text Contents: synopsis Old/Default contents: [return keeps contents] >> New version caused fixed disk to explode upon installation of software Was stored successfully with id defect2 |
When you submit a new report, Yaktrack will create a series of menus and prompts to walk you through the submission. Once you have completed the submission, Yaktrack will tell you where the submission was located on filing (see the file command for further explanation).
If you don't want to use the simple text menus and prompts, you can set the YAKTRACKEDITOR environment variable to the path of your favorite editor; Yaktrack will create a "blank" issue for you to edit and invoke your editor on it; just save the edited file to disk and exit the editor to submit your report. However, you should be aware that the file will be XML text and may be difficult to work with without an XML-capable editor (Emacs, with the psgml major mode, is one good choice). Because of this, it is easier to submit invalid reports using the external editor method, but it is there for your convenience if you wish.
The file command is used to file a preformatted issue, and is the "back end" for the submit and edit commands. The file command loads the file from disk, checks it for validity, and (if it is valid) assigns it an identification number and stores it in the repository. If the file is invalid (for example, does not match the template), its text is stored in the awaiting-review directory instead. Either way, the result is communicated to the user. In the following example, the user is trying to submit a totally invalid report:
[vputz@yak_prime temp]$ cat > garbage Blah, blah. Yackety smackety. (Ctrl-D) [vputz@yak_prime temp]$ ../yaktrack.py file garbage Issue garbage was invalid for the following reasons and was filed as 'awaiting-review' under id awaiting-review1 'garbage':2:1: Character data not allowed outside root element 'garbage':2:1: Premature document end, no root element [vputz@yak_prime temp]$ |
The file command is actually rarely used in normal operation; typically, command-line users will use the submit or edit commands instead. However, in the event that you have a preformatted issue, you can use the file command directly. Note: if you obtain an issue via "cat" and change the "yaktrackid" of the root element, you will overwrite the issue with the new "yaktrackid"!. Yaktrack uses the "yaktrackid" to identify issues and define where they should be kept, so never change this value!
In the example below, the user has filled out a file with a valid defect and is using the file command to insert it into the repository:
[vputz@yak_prime temp]$ cat defect2file <?xml version="1.0"?> <!DOCTYPE defect SYSTEM "defect"> <defect yaktrackid='defect2' confidential='no' test='new_value'> <submitterid>vputz@wingedyak.com</submitterid> <originator>Winged Yak Productions testing facility</originator> <synopsis>New version's installation program highly unstable; addresses hardware detonator registers in an unsafe manner</synopsis> </defect> [vputz@yak_prime temp]$ ../yaktrack.py file defect2file Was stored successfully with id defect2 |
A very commonly used command, edit is used to edit an existing issue. To use it, you must know the ID of the issue you wish to edit; if you fail to provide a template or ID, edit will list the available templates or IDs for you. Like submit, edit will either use an internal "editor" of menus and prompts or an external editor if the YAKTRACKEDITOR environment variable is set to the path of an editor. Below, the user is editing the issue he submitted earlier:
[vputz@yak_prime temp]$ ../yaktrack.py edit defect defect2 Attribute: (defect:confidential) 1 . yes 2 . no [ 2 ] >> 2 Attribute: (defect:test) Old/Default contents: test [return keeps contents] >> new_value Text Contents: submitterid Old/Default contents: vputz [return keeps contents] >> vputz@wingedyak.com Text Contents: originator Old/Default contents: Winged Yak Productions testing facility [return keeps contents] >> (presses return) Text Contents: synopsis Old/Default contents: New version caused fixed disk to explode upon installation of software [return keeps contents] >> New version's installation program highly unstable; addresses hardware detonator registers in an unsafe manner Was stored successfully with id defect2 |
As in submitting a report, pressent the "return" key at a prompt keeps the default contents -- in this case, the contents from the previously submitted report. Once the report has been filled out and edited, it is refiled automatically using the file command.
Once issues have been submitted, it is sometimes useful to list them in full. To do this, use the cat command, named after the Unix shell command of the same name. The operation is fairly simple; provide cat with a template name and an issue id, and Yaktrack will list that issue for you. If you fail to provide a template name or an issue ID, Yaktrack will list the available templates and issues. Below, the user is listing the entry he just edited:
[vputz@yak_prime temp]$ ../yaktrack.py cat defect defect2 <?xml version="1.0"?> <!DOCTYPE defect SYSTEM "defect"> <defect yaktrackid='defect2' confidential='no' test='new_value'> <submitterid>vputz@wingedyak.com</submitterid> <originator>Winged Yak Productions testing facility</originator> <synopsis>New version's installation program highly unstable; addresses hardware detonator registers in an unsafe manner</synopsis> </defect> |
Unfortunately, the current cat output consists of the raw XML text of the submitted issue, which is not always the easiest thing to read. Future versions of the cat tool may improve this output.
The query command queries the repository database using a very small query language similar to XPath or XQL. A string of query text looks almost like a directory path, with names separated by slashes; the names represent nodes in the issue template structure. For example, the simple defect template we've been discussing consists of a "defect" with attributes "confidential" and "test", and children "submitterid", "originator", and "synopsis". If we wanted a list of all defects in your database, we could always do something like the following:
[vputz@yak_prime temp]$ ../yaktrack.py query defect defect <defect yaktrackid='defect2' confidential='no' test='new_value'> <submitterid>vputz@wingedyak.com</submitterid> <originator>Winged Yak Productions testing facility</originator> <synopsis>New version's installation program highly unstable; addresses hardware detonator registers in an unsafe manner</synopsis> </defect> <defect yaktrackid='defect3' confidential='no' test='test_value'> <submitterid>jocarter</submitterid> <originator>Winged Yak Tech Support</originator> <synopsis>User complained of blurred vision and a proliferation of bats on software exit</synopsis> </defect> <defect yaktrackid='defect4' confidential='yes' test='test_value'> <submitterid>jocarter</submitterid> <originator>Winged Yak Tech Support</originator> <synopsis>After installation of software, user reported that server case was full of eels.</synopsis> </defect> |
Of course, listing the full text of all defects may not be very useful. If you only wish to list parts of all defects, you could extend the path. For example, to see all the synopses of submitted defects, our user could do the following:
[vputz@yak_prime temp]$ ../yaktrack.py query defect defect/synopsis <synopsis>New version's installation program highly unstable; addresses hardware detonator registers in an unsafe manner</synopsis> <synopsis>User complained of blurred vision and a proliferation of bats on software exit</synopsis> <synopsis>After installation of software, user reported that server case was full of eels.</synopsis> |
Still, we're getting information from all defects. It would be more useful if we could cull this information by selecting certain nodes for display. This is done by adding a selection clause (or clauses) in brackets after each name in the query expression. By way of example, let's select the synopses of all defects where the submitter is "jocarter":
[vputz@yak_prime temp]$ ../yaktrack.py query defect defect[submitterid="jocarter"]/synopsis <synopsis>User complained of blurred vision and a proliferation of bats on software exit</synopsis> <synopsis>After installation of software, user reported that server case was full of eels.</synopsis> |
The values in quotes are match strings that are used to test the child node's content; they follow standard regular expression matching conventions.
Finally, attributes can be used in selector clauses as well. To use them, you must prefix their name with an asterix. You can chain multiple selector clauses in a query string, making for fairly flexible queries. In our last query example, the user queries for the full text of all defects with the attribute "confidential" set to "yes" and the child submitterid set to all submitters whose identifications begin with the letters "jo":
[vputz@yak_prime temp]$ ../yaktrack.py query defect defect[submitterid="jo.*"][@confidential="yes"] <defect yaktrackid='defect4' confidential='yes' test='test_value'> <submitterid>jocarter</submitterid> <originator>Winged Yak Tech Support</originator> <synopsis>After installation of software, user reported that server case was full of eels.</synopsis> </defect> |
The query functionality is currently rather inefficient, and on large databases queries may take some time. However, it does provide a fair amount of expressive power, and is useful in practice (the requirements traceability matrix in the Yaktrack requirements document was produced by a script which used query, in fact).