This is the Tracknet 1.02 user and system documentation.
Configuration is covered in configuration.html. Customization will be covered in another document
This is the login page. Just enter your username and password and hit the login button. There is also a Save Login checkbox to have the package remember that you are logged in between browser sessions. You will have to have cookies enabled to login.
If the account doesn't exist, the account is disabled, or the password is incorrect then you will remain at the login page. An error message will be displayed.
The administrator may allow users to sign up for their own accounts. If so, a link to Signup for your own account will be available.
The administrator may also have anonymous login allowed. Anonymous users will be logged in under a common account.
You will be allowed to select a project to work in after logging in. You can make a project your default selection from the Select Project screen or from your Account Options.
[ Select Project ]
A list of projects that you are allowed to access will be displayed. If no projects are available then you cannot login. Contanct the administrator to have projects made public or to assign you to have access to certain projects.
[ Signup ]
Here you can signup for a new account. You must supply a valid email address and select a unique username. Your randomly generated password will be emailed to your email account.
This is the first page you see upon logging in. It shows you the latest news updates for the Tracknet. This is a simple news module (based off of work by Scott Roberts) and is to keep users abreast of changes in the Tracknet or project. Some news postings are specific to projects and others are global across the entire Tracknet. This is set at the time of posting in the Edit News section.
The number of news posts is controlled by a global variable. When the number of posts is more than the limit, a link to show "older news" is displayed at the bottom. Similarly a "newer news" is displayed when you have clicked on "older news".
There is an Archives option at the bottom of the page to view all listings.
[ Archives ]
A title/date/poster listing of ALL past news articles will be listed here. Clicking on the link will bring up the specified article. This listing will also only display items that are either global or specific to the selected project.
It would be useful to be able to tell when a post is sitewide or just specific to the project.
Here we can view the bug listings. The page has a set of viewing filters at the top and the bugs are listed below.
The filters control the behavior of the Bug List. The filters are saved between browsing sessions but do not currently save sort order or direction.
If the number of bugs exceeds the "Show" count in the filter a link for the "Next XYZ" bugs will be displayed at the bottom. Appropriate "Prev XYZ" bug links will also be displayed.
The Search field will look for simple keyword matches in the summary, description, steps_to_reproduce, additional_information, bug id, or bug text id fields. It does not currently search through bugnotes.
The bugs are listed in a table and the attributes are listed in the following order: priority, id, number of bugnotes, category, severity, status, last updated, and summary. Each (except for number of bugnotes) can be clicked on to sort by that column. Clicking again will reverse the direction of the sort. The default is to sort by id in descending order.
The bug id is a link that leads to a more detailed report about the bug. Depending on what you have set in your Account Preferences you will be sent to the simple or advanced view. You can also add bugnotes here.
The number in the bugnote count column will be bold if a bugnote has been added in the specified time frame.
The text in the "Severity" column will be bold if the severity is major, crash, or block and the bug not resolved.
The text in the "Updated" column will be bold if the bug has changed in the last "Changed(hrs)" field which is specified in the viewing filters.
Each table row is color coded according to the bug status. Here is an explanation of the default colorings:
color coding
severity
status
projection
[ View Bug Simple ]
Here is the simple listing of the bug report. Most of the fields are self-explanatory. "Assigned To" will contain the developer assigned to handle the bug. Priority is fully functional but currently does nothing of importance. Duplicate ID is used when a bug is a duplicate of another. It links to the duplicate bug which allows users to read up on the original bug report.
Users with an access level of Updater, Developer and Administrator can usually also Update Bug or Delete Bug (some of this can be configured). It is recommended against deleting bugs unless the entry is frivolous. Instead bugs should be set to resolved and an appropriate resolution category chosen.
Below the bug information there may be a form for uploading file attachments. The Administrator needs to configure the Tracknet to handle file uploads. If uploading to disk is selected, each project needs to set its own upload path. Uploading to the database is the simplest and recommended method.
At the bottom of the bug report are any attached Bugnotes. Only users with Viewer access are precluded from adding Bugnotes.
[ View Bug Advanced ]
The Advanced View is much the same as the Simple View with a few additional fields. Here you can see Projection, ETA, Votes (all which currently have no real effect), Platform, OS, OSBuild, Product Version, Product Build, and Steps to Reproduce. There is also an button.
These options are only available to Updaters, Developers, and Administrators.
[ Update Bug Simple ]
Here you can update various bug fields. The Category, Severity, and Reproducibility fields are editable but shouldn't be unless there is a gross miscategorization.
Also modifiable are the Assigned To, Priority, Projection, ETA, Resolution, and Duplicate ID fields.
[ Update Bug Advanced ]
More fields cna be updated from this page.
[ Assign To Me ]
If you are a developer you can use this as a one click "assign to me".
[ Resolve Bug ]
This option on the View Bugs page allows you to resolve the bug. It will lead you to a page where you can set the resolution state and a duplicate id (if applicable). After choosing that the user can choose to enter a bugnote detailing the reason for the closure. The bug is then set to the Resolved state. The reporter should check off on the bug by using the Close Bug button.
[ Close Bug ]
If the bug is currently Resolved you can use this to finally Close the bug. At this state there is confirmation that the issue has been satisfactorily resolved.
[ Delete Bug ]
This allows you to delete an existing bug. This should only be used on frivolous or test bugs. A confirmation screen will prompt you if you really want to delete the bug. Updaters, Developers, Managers, and Administrators can remove bugs (you can also configure this).
Everyone except Viewers can add bugnotes. Only the submitter and Administrators and Managers can delete bugnotes. If the bug is Closed or Resolved then you cannot Add Bugnotes. You will have to Reopen Bug before you can add another bugnote. Administrators and the submitter can also edit their bugnotes.
[ Add Bugnote ]
Type in whatever additional information that you remember, ask questions regarding the bug, make suggestions as to the bug fix. Line breaks are preserved (converted to <br>) and limited html may be allowed. These HTML settings are set by the administrator in the config settings.
[ Delete Bugnote ]
Just click on the Delete Link to remove an unwanted bugnote. There is no confirmation screen.
[ Reopen Bug ]
If the bug is currently Resolved or Closed you can use this to Reopen the bug. Then you will be allowed to enter further bugnotes. The bug will automatically be put into Feedback status.
Here you can report new bugs. Depending on your Account Preferences and the site and project settings, you will be sent to the simple or advanced report forms. Newly reported bugs are, naturally, put into the new bug status.
[ Report Bug Simple ]
The simple form lets you report the category, reproducibility, severity, summary, description, and additional information category. All but Additional Information are required fields.
Summary should be a short, one sentence description of the problem. It has a limit of 128 characters. Help out the developers and don't insert useless or misleading lines like "it doesn't work" or "it crashed" or "this sucks".
[ Category ]
Select the most appropriate category for the report. These categories are defined per project by the project administrator. The administrator should provide an "other" as a catch-all category.
[ Reproducibility ]
Reproducibilty is the key to being able to quickly fix a bug.
- always
- sometimes
- random
- have not tried
- unable to duplicate
[ Severity ]
Severity often dictates what bugs need to be fixed in order for a product to be shipped. Normally a product should not ship with any major or higher bugs unless they occur very infrequently.
- block - prevents further work/progress from being made
- crash - crashes the application or OS
- major - major bug
- minor - minor bug
- tweak - needs tweaking (graphic alignment, formatting, etc.)
- text - error in the text, grammar, wording, etc.
- trivial - being nitpicky
- feature - requesting new feature
[ Summary ]
A brief one line description of the problem. Help out the developer by actually making it descriptive and meaningful.
[ Description ]
A detailed description of the problem. As a rule of thumb you should always enter enough information for the developer to feel like he is in your shoes. Describe what you were doing, what you expected to happen, what should have happened, the error, setup and system settings, software version(s), and possible ideas and suspicions.
[ Additional Information ]
Any extra information that you didn't put into the Description should go here. This might be a dump of your error, a proposed fix, or anything that is related to but not directly a part of the bug.
[ Report Stay ]
Report Stay displays a button that read "Report More Bugs" after you submit the bug. The button allows you to return to the report bug screen after submitting a bug and it will automatically fill in most of the pertinent settings from the previous bug (category, severity, and more). This is useful when inputting multiple bugs at once.
[ Report Bug Advanced ]
The advanced form has, of course, more fields to fill in than the simple version. It has, in addition to the simple form fields, an option to choose between choosing an existing Account Profile or filling in the computer platform, operating system, and operating system version/build, product version, product build, and steps to reproduce. You may optionally directly assign a bug to a developer.
[ Steps to Reproduce ]
List the detailed steps to reproduce a problem. This is useful for bugs that take a while to show up or tricky cases. A developer will take an order of magnitude more time to fix a bug that is not easily reproducible. So, if at all possible go back and try to reproduce the bug. It would be best to use a format that looks like.
1. step 1
2. step 2
3. step 3
This shows a detailed summary of the state of the Tracknet according to several (hopefully) useful metrics. This section is in its infancy and will eventually include a useful set of metrics, graphs, and reports.
This page allows the user to change his username, email, and password. It also has subsections to Manage Profiles and Change Preferences. If an admin has "protected" the account then the user is not allowed to access account. This is to allow single access public accounts (like a guest account).
[ Change Preferences ]
This page allows the user to specify several user preference choices.
You can reset the defaults with the "Reset Prefs" button. The administrator sets the default values in the configuration file.
- Default Project - This is the project you are automatically logged into when you log into the Tracknet
- Advanced Report
- Advanced View
- Advanced Update
- Refresh Delay - You can set the view bugs pages to refresh every X minutes. 0 means never refresh (you have to do it manually) and the administrator can set a minimum refresh setting. The minimum setting exists to prevent too many users from hammering on the server
- Redirect Delay - Each action page has a delay value that you can set. Minimum of 0
- Email on New - Email you if you are a Developer, Manager, or Administrator when a new bug report is filed.
- Email on Assigned - Email you when a bug you are attached to is set to assigned
- Email on Feedback - Email you when a bug you are attached to is set to Feedback status
- Email on Resolved - Email you when a bug you are attached to is set to Resolved status
- Email on Closed - Email you when a bug you are attached to is set to Closed status
- Email on Reopened - Email you when a bug you are attached to is Reopened
- Email on Bugnote Added - Email you when a bug you are attached to has a Bugnote added
- Email on Status Change - Email you when the status of a bug you are attached to is changed (NOT IMPLEMENTED)
- Email on Priority Change - Email you when the priority of a bug you are attached to is changed (NOT IMPLEMENTED)
- Language - Select your preferred language
Future user level default preferences will be displayed here.
[ Manage Profiles ]
Here you can add new profiles. This is useful when you don't want to keep re-entering your system configuration in the Advanced Bug Reports. It allows for multiple bug reports for multiple system configurations. There is a "Description" field as a catchall for more details
You can also edit, set different profiles to be defaults and delete profiles. To set your account to have no default just select the blank profile and choose "Make Default".
It would be really useful for projects to be able to tailor what their reporting needs would be. This would also be reflected in the Advanced Bug Reports section.
This section is reserved for Managers and Administrators.
Here a manager or administrator can specifically assign a user to a project. They can be assigned at an arbitrary access level so a developer could be 'demoted' to a updater for this specific project.
Conversely a reporter could be 'promoted' to be a developer.
To limit access to a project to all users you should make the project private. You can do this via the Manage | Manage Projects subsection. You will then have to manually assign users to be added to the project. Public projects are open to all users at their default acces levels. You may override these levels.
This section is reserved exclusively for Administrators.
[ Manage Users ]
The main Manage page shows a list of users and their relevant info. Username, email, access level, enabled status, protected status, date created, and last visit. From here the admin can choose to edit the user's info. If people can signup for accounts and the admin chooses to reset the users information the user's password will be randomly generated and emailed to the user. If users cannot signup for accounts the password will be set to be blank. There is currently no way for a user to be notified of his password should he forget it.
This section displays all accounts created in the last week as well as those that have never logged in. The Prune Accounts link will delete all accounts older than 1 week that have never logged in.
[ Manage Projects ]
Projects are handled from this section. You will see a listing of each project as well as an Add Project form at the top of the page. You can edit the categories and versions of a project by clicking on the Edit link. If a project is marked private it will be hidden from non-Developers/Managers/Administrators. Disabled projects are hidden from all but Administrators. The status of a project can also be selected (development, release, stable, obsolete). The description currently is only displayed in this section.
If file uploads are sent to DISK, the upload file path is where project documents and bug file attachments will be stored (if the option is enabled in the config settings). This directory must be writable by the webserver. As a result this is most useful in private Intranet settings. Public web hosts are unlikely to grant such permissions to users. Storing into the database is recommended for security reasons.
In the edit project section you can update the project information, delete the project, or add versions and categories. You can also update and delete the versions and categories.
Remember to add at least one category for your project!!! Otherwise, you won't be able to enter bug reports.
[ Create Account ]
Create a new account in this section. Default is to have the account enabled and set to reporter. Currently this does not send an email to the user.
Access Levels
The access levels will continue to grow in capabilities as more features are added to the package.
- viewer - Can only browse and view bug listings (eg. guest accounts)
- reporter - Can report new bugs and add bugnotes
- updater - Same as reporter and can update bugs (eg. trusted testers, power users)
- developer - More privileges than updater. People working on the project
- manager - More privileges over Developers. Can assign others to any projects that are being managed. Can also make news postings.
- administrator - All powerful account. Can create accounts, reset passwords, remove users, and more.
Managers and Administrators are allowed to make news posts from this section. These posts show up in the Main section.
[ Add News ]
Enter a headline and then the message. Line breaks will be preserved (converted to <br> tags). Do not use the " character in the headline. It will be converted to a ' if you do. The " character confuses the Edit Post drop down list as well as the text input field when editing.
Also select the project that the post will be posted to. By default the currently active project will be selected. You can select a sitewide post if you wish the news item to appear on every single news page. Posts in this category would affect all projects of the bug tracker. This is useful for spreading information such as system downtime, upgrades, global changes, and so on. Only Administrators can select sitewide posts.
[ Edit/Delete News ]
At the bottom you can either edit the selected post or delete it. The default action is to edit the post. You will be taken to a screen where you can edit the post. If you choose delete then you will be taken to a page requiring delete confirmation. The drop down list is populated only by the posts that the logged in user posted unless you are an Administrator in which case all posts will be displayed. Only administrators are allowed to modify posts made by other users.
This deletes the user cookie and redirects the user to a specified page (default is to redirect to the index page which redirects the user to the Login page)