As mentioned before, the design of YakTrack is layered, leaving three primary modes of operation roughly corresponding to user classes: immediate (expert or knowledgeable user), email-gateway (less-experienced or less-trusted user), and web-based (novice user, although suitable for other experience levels as well).
YakTrack is operated in immediate mode when the user has their own copy of the issue-tracking repository. Since the issue-tracking repository is assumed to be part of the development repository, this means that all developers have access to the issue-tracking repository (the converse is not necessarily true; it would be possible to have a standalone issue-tracking repository, or (if the configuration management software allowed it) to prevent some users from accessing the rest of the development repository).
Because most users with full access to the development repository are assumed to be experienced users, the immediate-mode tools are designed as command-line tools (nothing prevents designing an immediate-mode tool which uses a gui to script the command-line tool, using Python and TKInter, for example; however, such tools are not an immediate part of this submission). The command-line tool uses a "nested command" structure like that used by CVS; for example, rather than having separate file and query root commands, users would type yaktrack file or yaktrack query). When invoked, YakTrack "climbs up" the directory structure until it finds a repository in a subdirectory, loads appropriate extensions (see the design outline), and executes. Thus if an issue-tracking repository is placed in the root directory of a development repository, YakTrack can be used from anywhere in the development repository.
All commands, if left unfinished, will display a short help message giving help on the next possible steps (for example, simply typing yaktrack file should give help on filing a report). All commands will display some sort of feedback message concerning the initiation of the command and its outcome, with reasons for failure or results of success clearly defined; for example:
[vputz@yak_prime yak4] yaktrack file -f sample-report.xml YakTrack: submitting new report using template blurfl.dtd... template not found: blurfl.dtd report awaiting review as awaiting-review/1.xml
In the above example, the submitted issue report did not use a template in the repository, and was thus unfileable; rather than discarding it, though, YakTrack has filed the report as "awaiting review" and communicated that information back to the user. A summary of the most commonly used immediate-mode commands follows:
Create-repository. The command yaktrack create-repository checks to see if a repository exists under the current directory; if not, it creates the subdirectory yaktrack-repository, copies any default data into it, and (if it recognizes the given configuration management setup) adds it to configuration management. The repository is now essentially ready for use, although experienced administrators may opt for further configuration by editing, deleting, or supplementing the standard templates.
File. The most commonly used command (aside, perhaps, from its cousin submit), file files a status report, either from a file (using the -f parameter) or from standard input, incorporating attachments with the --with-attachments filename filename... parameter. The text of the report is read in and parsed; if found to be valid XML and to match one of the existing DTDs in the repository, it is assigned an identification number and placed into the repository. If the report is invalid, it is assigned an identification number and placed into the awaiting-review subdirectory. The default behaviour of file involves updating the repository via CM prior to generating an ID and filing the report, and adding the new file to CM after storing it to disk; if this sort of constant CM use creates performance problems, it can be changed by modifying the file command object in the base YakTrack tool (see the design outline for a description of this customization).
Query. The query subcommand is used to retrieve the text (or part of the text) of a previously-submitted issue. The primary method of searching is to query a given field for a string of text using standard regular expressions, ie yaktrack query defect STATUS="fixed" SUBMITTER="*wingedyak.com" would find all issue reports using the defect.dtd template in which the STATUS field was equal to the text string "fixed" and the SUBMITTER's name ended in wingedyak.com. The default response prints the identifiers of reports which match the criteria; additional command-line flags garner more information (-F or --full, for example, prints the full text of the issues).
Submit. A trickier-to-implement command, submit is more interactive than file, which assumes preformatted XML input. The submit command, on the other hand, interactively prompts the user for input based on the required DTD elements, then calls file to actually file the new report. From the DTD, it will generate a series of prompts and menus, gathering information from the user; while GUI options could be made available via TkInter, a simple text interface is shown below:
[vputz@yak_prime yak4]$ yaktrack submit YakTrack submit: You must select a template. The following templates are available: defect use-case [vputz@yak_prime yak4]$ yaktrack submit defect YakTrack submit: You are submitting a new defect; please follow the prompts: Element: Defect; Attribute: Priority Please select one: 1. low 2. medium 3. high --> 1 Element: Defect; Element: Originator Please type your response; press enter to terminate --> vputz ...
Edit. Edit is simply a query for full text followed by an editing phase, followed by a file command using the same ID (to replace the original submission). The edit phase is the one which deserves some configuration, with the standard (default) setup being to run the editor labeled in the YAKTRACK_EDITOR environment variable (it would also make sense to do this via the yaktrack-options directory somehow, but this would customize the editing tool to the repository, rather than to the individual user; the latter behaviour is probably preferred, given the iconoclastic text editor choices of many software professionals!). Some other editing options (aside from a straight text editor) might include a gui widget (based on TkInter, for example) which generates forms based on the root DTD in the same way that the web gateway would.
Less-used commands will include check-integrity (to verify the integrity of the issue repository), merge-issues ( which merges two issues by ID by naively combining fields from both reports, leaving "pointer" reports in the originals and filing a new report for the merged result), split-issue (which splits an issue by forking it into two subissues, which must be edited by hand to contain the requested information, and leaving a "pointer" report in place of the original), and is-valid-dtd (to check whether a given DTD is acceptable for YakTrack -- see the "What do you mean by "simple" DTD?" sidebar). Further extensions in immediate-mode could include such functionality as producing a summary document suitable for printing through transformation of the XML reports via DSSSL or other tools. These extensions would likely be implemented by adding commands to YakTrack at run-time.