Welcome to the home of BITS
|
|
BITS installation instructions and walkthrough
BITS is a Bug Identification and Tracking System. It is similar to Bugzilla in concept but has an unique design, implementation and workflow. BITS supports multiple concurrent projects, small or large and is currently targeted at corporate-style environments.
BITS possess a complete and working set of bug reporting tools:
- Bug submission interface.
- Report viewing and editing interface.
- Flexible and powerful search interface.
- Two levels of report scheduling.
- Support for history logs and reports.
- Email notification (based on PhpMailer library).
- Database administration tools.
- Support for multiple projects in a single database.
BITS is being developped on Linux. It is written in PHP and relies on a MySQL InnoDB database.
BITS is innovative:
Keeps track of test results for all tested versions (test reports).
Keeps track tested platforms and affected platforms. If you test cross platform products, you know how annoying it can be to accurately track tests on different platforms. BITS makes it easy.
Checkin notification offers a way to tell when changes become effective and in what branches.
Has an interactive Javascript interface for setting bug priorities (the closest thing from drag and drop you can get with Javascript).
Has an interactive interface for customizing bug listings : each user can choose what fields to display, in what order to display these fields and what sort to apply on them. Each layout may be saved separately and recalled easily.
Has per-project preferences. Allow users to save their settings on a per-project basis.
Fully takes advantage of the InnoDB database type:
Row locking favors concurrency.
Transactions and foreign key constraints makes it more robust and safe.
Note that BITS is under active development. Database structure changes are still possible. We will do our best to explain changes and to help our users migrate their data.
BITS has a rudimentary permission system. For this reason, BITS is intented to be used in closed circles. This limitation will be lifted in a future version.
BITS is published under the GPL.
More features are planned to be included into BITS in the next months. Items below should be implemented before we hit v1.0. Regular maintenance, requests and new ideas are excluded.
Pending:
Major structure upgrade : meta history table, dedicated scheduling table, real guids for identifying history records, foreign key and index review.
File attachments.
Read/write report mode for quickly editing reports (not all fields).
Bug reviewing facilities.
Implement report generation interfaces : recent database activity, by-version resolved bugs, by-version and by-area new bugs.
Completed in 0.40 release (2004/05/--):
Major user interface upgrade. Got rid of the universal edit form to the profit of smaller and easier to use interfaces. This was requested by many.
Improved internals. Database changes made easier and safer.
Preferences to open new windows when typing in the goto# box or clicking bugs in the search results.
Separation of user comments and report description in different tables. It was a design mistake to combine the two.
Completed in 0.39 release (2004/01/17):
Enhanced report history.
Email notification for report updates (requested).
Completed in 0.38 release (2003/11/11):
Ability to save form state (added on 2003/10/18).
Bug prioritizing interface (requested).
Added keywords field in reports (requested).
Enhanced substring search (requested).
Completed in 0.37 release (2003/10/18):
Customizable report output: ability to select columns to display in a report, their sequence and sort order.
By-project preferences.
Permission system. Based on PHPLib?
Implement a registration system for outsiders to access a BITS database, facility for identifying project members.
Centralized and seamless error management capable of handling SQL, PHP and program errors and warnings.
Redo the interface in DHTML. Be fully compliant with W3C standard. Have a nicer look.
Project policies : which fields are mandatory, which are not, fields to be disabled or hidden at all times.
Way of archiving and restoring old bugs to optimize database size.
- MySQL 4.0 or better, with InnoDB support enabled.
- Apache 2.0 or better
- PHP 4.1 or better
Email notification requirements:
- PHPMailer 1.71 or better.
- A Mail Transfer Agent supported by PhpMailer (ex Sendmail).
BITS uses JavaScript extensively to enhance user interfaces. Make sure JavaScript is turned on. The following browsers are supported:
IE v5+
Mozilla 1.3+
Konqueror 3.1+
Database setup
These instructions assume you have installed, configured and tested MySQL with InnoDB support and PHP 4.1.
These instructions assume you have a ~/my.cnf file defined. Without this file defined, you may have to specify the "-u user" switch and type your password for every MySQL command. A minimal my.cnf config contains the following:
[client]
user
= mydbuser
password = mypass
#port = if needed
#socket = if
needed
First, create your BITS database and import the database structure:
$
mysqladmin create bits
$ mysql -D bits < sql/base.sql
$
mysql -D bits < sql/sample.sql
Create a MySQL user dedicated to the BITS database. Make sure to replace occurences of "bits.*", "bits@localhost" and "bits_password" by appropriate values for your system.
$ mysql
-e "GRANT
SELECT,INSERT,UPDATE,DELETE ON bits.* TO bits@localhost IDENTIFIED BY
'bits_password'"
$
mysqladmin flush-privileges
Copy the PHP tree under your web server tree:
$ cp -r php/* /var/www/html/bits
Edit config.php to reflect your configuration:
$config['database_url']
= "http://hostname/bits/";
$config['database']['host'] =
"localhost";
$config['database']['name'] =
"bits";
$config['database']['user']
= "root";
$config['database']['pw'] = "";
Open BITS in your web browser. Log in the database as "root@localhost". Leave the password field blank. You're in!
Walkthrough
BITS shares many concepts with other bug tracking systems. That makes it easy to understand in general, but it has some features of it's own that need to be understood. They will be covered in this quick walkthough.
The walktrough assumes your BITS database has been successfully installed.
Project setup
When you login into BITS the first time, you will land in the Find page. No serious bug tracking can be started at this time. The database needs to know more about your projects. Head to the Admin section.
The Admin section offers a set of simple (and admitedly rudimentary) interfaces to manage your BITS database. To start tracking bugs for a project, you need to do four things.
Create Modules and Components
These help identify where in the software bugs are found and who should fix them. Each Project may have one or more Modules. Each Module may have one or more Component. It is up to you to organize Modules and Components logically for your project. In the original design, Modules were meant to represent the various executable files of a project, Components were intended to represent the features of each program in the project. In the future, they may be renamed to Feature and Subfeature.
Identify Supported Operating Systems for your project
In the Operating Systems page, add the name of operating systems supported by your project if it is not listed already. This list is general. Theoritically, it should include every living OS out there. You shouldn't have to edit this often.
What's more important is to tell the database what is the Operating System Support for your project. The OS you select for a project will determine for which platforms it is possible to submit test results.
Identify Branches and Builds available for testing
BITS is keen on tracking test results. It will remember all results you will ever submit for any given report. It is a standard method of remembering what versions of the software and what platforms have been tested. Part of this standard process is to Register branches and builds as they are created or released. By registering branches and builds, you facilitate the tracking of tested versions: you know what versions have been sent to test. The system uses the information to validate submitted test results (results must be related to a valid version). Ultimately, this information may be used to find what bugs were active in a given version at a given time.
So, what values should you give Branches and Builds? A version branch should correspond to the branch of the repository it is coming from. When you create a branch in CVS, you should add the same branch in BITS. BITS makes a distinction between versions of programs built from different branches. Programs coming from different branches are simply considered different.
When creating a branch, you can optionally make it the default. You should make a branch the default when it is used for current development. This will have BITS suggest this value for all new checkin notifications. Each user can override the default branch in his preferences.
To identify a build, you must supply it's branch and it's creation date. Technically, a build's creation date is the date at which the source checkout was made. You may optionally assign an alias to a build. The alias is simply another way of remembering a build branch and date. The build alias must be unique within it's project and branch. The build alias can be a sequential number, but only if the number is never restarted at 1 for the project. If you wish to restart numbering builds at 1 for every branch, then a valid build alias would be "1.0.1.nnn".
Any build can be made the default. You should make a build the default when it is the main testing target. BITS will suggest the build id automatically in the test submission interface. Each user can override the default branch in his preferences.
You may need to review your build process slightly. Your program should carry the build information in it's About box. It is important to find easily what is the branch and build people are referring to when reporting problems.
Additional users
Database users are managed manually. Create yourself and your team mates a login.
Users with the Admin flag have access to the Admin section and the Schedule interface. Give a tester the admin flag when you want them to have the ability to register builds.
All users have access to all projects.
Report submission
Now that your project is setup, you can start submitting bugs. Head to the Submit page.
The Submit page is where you submit information about a bug or a request. Reports are always numbered starting at 1 for each project. This decision has been taken to facilitate report import from different databases without renumbering reports.
The report submission interface is straightforward. Simply fill the blanks.
BITS has a permissive behavior. The only required field for a new report is the summary, but it is recommended to always submit test results and a description.
Test results are generally expected to have:
1) At least one tested platform.
2) At least one platform affected by the bug.
3) A valid id of the version to which the results apply.
If you register Branches and Builds in the database as you create them, and if you set the default test build, then submitting test results becomes a no brainer : just click the platforms you have tested. To help the report submission, you sould always register builds as your release them and update the current test build.
The version id will typically refer to registered versions. Registered versions are those you have built and released to testers through your usual channel, then got registered in the bug database.
It is however possible at some point that developpers will want to track bugs they have found in their development tree (ie, a bug found in someone else's code). To track these issues, select the "Unregistered build" box and type an approximate date of your last development tree update or checkout. The date will not be validated, but it should be as precise as possible. A build date is always required when filling a test report.
The test report interface will propose a default branch and build based on the system default and the current user preferences. If the user prefs do not set a default build, then the system default will be used.
Finding reports
Once your database contains reports, there is no doubt you will want to review them. This is done through the Find interface.
The Find interface allows complex searches. It understand the following text search tokens
optional_word
"optional
string"
+mandatory_word
+"mandatory
string"
-excluded_word
-"excluded
string"
word*
*word
*w*o*r*d*
The Find interface can save and recall your search parameters. It can also output the fields you want in the order you want with the sorting you want.
- To save or recall search options, use the "Form Options" section.
- To select or customize your list layout, use the "Report Options" section.
To open a report, simply click it's Title or the View link.
If you know a report number, you may also access it directly by typing it's number in the Goto# box.
Report viewing and editing
Accessing a report opens it directly in edit mode. This form acts as a platform for all editing needs.
The form allows a certain number of fields to be edited directly. It is not however meant to be used directly to resolve, close or reopen reports. At the top of the page, you will find Resolve, Close and Reopen links (following the report status). Use them to perform the corresponding operations on a report.
Bugs generally go through three Stages : Active, Resolved, Closed. Submitting or reopening a bug makes it Active. Developpers set reports to Resolved when they no longer need to work on them (the either modified the program, cannot reproduce, etc). Testers put the bugs to Closed when they no longer reproduce them in the current version.
Even when using the Resolve interface, BITS allows minimalist report resolution. The minimum information it requires is the resolution type. It is however highly recommended to take advantage of the checkin notification feature. It is simple to use : just tell what branches you made a change in, and when (approx) the change is becoming effective. This will help testers knowing what versions must be retested before closing the report.
The same goes with the Close interface. Even though you can close a report without giving test results, it is strongly recommended to tell in which version you consider the issue as closed. The same comment applies to the Reopen interface.
There is no specialized interface to assign, estimate or set a target for a report. Do it directly in this interface.
To add a comment to the report, scroll below the User Comments section and type in your own comment.
Pushing the Save All button saves all changes including a comment if there is one.
The description is not editable by default. This was a deliberate decision to allow full description to be read without scrolling a text field.
To add a test report or a checkin notification without affecting the report status, scroll to the appropriate section and click the "New" link.
It is encouraged to post additional test results as you gather them during your work. Posting all test results may sometimes be excessive. For example, if you test 5 builds to find when a feature broke, it may be enough to add results for two of them :
- For the build where the feature last worked.
- For the build that followed, where the feature stopped working.
When a version has been tested already and you want to add results for more platforms at a later time, edit the test result for this version.
Report Scheduling
BITS has two levels of report scheduling. The immediate and superficial way of scheduling a report is to give it a target version and assign it to a developper. The priority field may also be used to help determine what reports should be fixed first. This approach is good but has limits. Sooner or later, you will have more bugs than you can fix. You will need to decide what needs to be fixed first and what to fix first. This is where the Schedule interface comes handy. This interface allows to give developpers the exact priority of each issue.
Before you can use the Schedule interface, reports must have been given a target version and an assignee. Only then you will be able to load reports in the Schedule interface. To perform the first level of scheduling, use the report viewing/editing interface. Once you have done this, select the Schedule link.
When scheduling reports, you have two possibilities. You can schedule per version or you can schedule per developper. The two approaches are not independant. Try not mixing both.
Scheduling is simple :
- Pick a version (and a developper).
- Hit the Load Schedule button.
- Move report items up and down.
- When you are satisfied, Save.
To view the priorities, create a Find layout including the "Assignee" and the "Pri.#" field. Sort on the priority first, then on the assignee. It will list the reports in order of priority for each developper.
Note the priority number is indicative. More often than not, the priority numbers will more not produce a pretty sequential order. However, sorting them will always reflect the priorities you have set. What is important is the order, not the number. Priority numbers also shouldn't be compared when scheduling per developper. Developpers will be working simultaneously on different bugs in the order you've set.
Other notes
BITS is flexible. It allows a lot of shortcuts, such as closing a bug directly, submitting bugs without description and test results, etc. There is currently no way to reconfigure the default behavior.
Bugs generally go through three Stages : Active, Resolved, Closed. These statuses cannot be modified, as the program relies on them explicitely in the code.
You cannot change all resolution types. You must have at least these three: "Fixed", "Not Repro", "Duplicate".
Other list of values may be changed freely (bug types, priority names).
BITS has a loose security model : you either are admin or you are not. Admins have access to the "Admin" and "Schedule" links. Anybody may edit any part of a report: the detailed description, user comments, etc.
Enabling email notification
These instructions assume you have installed, configured and tested an MTA.
Download PHPMailer 1.71 or better and unpack it on your system.
Enable mailing in config.php and set the path to your PHPMailer installation:
$config['phpmailer_setup']['enabled']
= 1;
$config['phpmailer_setup']['path'] =
"/opt/php/phpmailer";
$config['phpmailer_setup']['sender_email']
= "NO_REPLY@localhost";
Tell BITS what is your mail server and how to connect on it:
$config['phpmailer_options']['Host']
= "mail.company.com";
$config['phpmailer_options']['Port']
= 25;
$config['phpmailer_options']['Mailer'] =
"smtp";
$config['phpmailer_options']['SMTPAuth'] =
false;
$config['phpmailer_options']['Username'] =
"";
$config['phpmailer_options']['Password'] =
"";
$config['phpmailer_options']['Priority'] =
3;
$config['phpmailer_options']['Encoding'] =
"8bit";
$config['phpmailer_options']['CharSet'] =
"iso-8859-1";
Users who want to receive all new bugs and updates should enable the reviewer status in their preferences.
Report submitters will receive all updates made to their reporrts unless they turn off their observer status for these reports (which they should not do).
Developpers are automatically made observers of the report they're being assigned, until they turn off their observer status for these reports (which they should not do).
BITS never removes an observer status by itself. If you assign a report to dev A, then reassign it to dev B, both dev A and dev B will be made observers of this report by BITS.