Feature FILE: File a preformatted issue to the tracking database

Description and Priority

All users, from local users to remote submitters, must be able to submit reports to the tracking repository. Once the SUBMIT feature has gathered this information and fed it to the appropriate gateway, the FILE feature stores the preformatted report in the database.

Stimulus/Response Sequences

FILE.UC.LOCAL: Local filing of a preformatted report


The user (or email gateway) files the report by invoking the command yaktrack file [filename...].


A repository can be found by backtracking up the directory tree
The user has write access to this repository


If the issue report is valid, a new report file exists in the repository containing the new issue
If the issue report is not valid (does not match one of the DTD templates) then a new file exists in the awaiting-reviw subdirectory of the repository.
In either case, feedback is given via standard input of the result; either a success message featuring the filename (ID) of the new issue, or an error message indicating the error and noting that the issue has been placed in the awaiting-review directory.
If the repository is set up such that all issue submissions must go through an issue manager, the issue is placed in the awaiting-review subdirectory of the repository.


Very high; any new submission generates a FILE request; any resubmission of an issue (such as one edited remotely and resubmitted) generates a FILE request.

Normal Course

Table 4-14. Normal Course of Events - from file

User ActionsSystem Actions
User invokes tool from command line via yaktrack file [filename...]Reads the file into memory as a list of lines
 Parses the stack of lines, locating the appropriate DTD and verifying correctess of the newly-submitted issue.
 Refreshes the local copy of the repository via version control
 If any errors, writes the buffer into a new file in the repository's awaiting-review subdirectory
 If no errors, and the system does not buffer issues for an issue manager(s), writes the buffer into a new file in the repository. If the system does buffer issues, writes the buffer into a new file in the awaiting-review directory
 If the issue is a new issue, generate an ID and store the new issue in a subdirectory of the issues subdirectory named according to the template; the issue's filename will be the same as its ID and stored in the issue as a root-level attribute named "yaktrackid" with a value identical to its filename.
 If the issue is an old issue (identified by the presence of the "yacktrackid" attribute at the root element), store it in the appropriate issues subdirectory with a filename equal to its "yaktrackid" attribute.
 Commit changes to version control, adding new files as appropriate.

Functional Requirements

FILE.FR1. The system should read a file from disk into an buffer

FILE.FR2. The system should identify the template used by the submitted issue and locate it in the repository

FILE.FR3. The system should parse the submitted issue and verify that it is a valid issue according to the stated template

FILE.FR4. The system should identify the presence of a "yaktrackid" attribute in the root element of the issue

FILE.FR5. If no "yaktrackid" attribute is present, and the system should create an id based on the filename used to store the new issue.

FILE.FR6. If no "yaktrackid" attribute is present, and the issue is valid, the system should add it to the issue at the root element.

FILE.FR7. The system should refresh the appropriate subdirectory of the repository prior to filing the new issue.

FILE.FR8. The system should file the new issue based on its "yaktrackid" attribute, replacing any existing file with the same name.

FILE.FR9. If the file is new, the system should add it to version control

FILE.FR10. Once the file is added or updated, the system should commit changes to version control.