paBugs 1 Documentation
Version 1.0 Beta

About
paBugs is a bug tracker designed to help developers organize bugs in their programs/scripts. It has an easy to use interface making browsing the database simple and a full featured easy to use admin center for managing the bug database. Written in PHP and using MySQL for the data backend, paBugs is a fast, server/CPU-friendly script.

Beta Info
This version of paBugs is a beta. Betas usually contain uncompleted features as well as unfixed bugs. Although there aren't any incomplete features and all known bugs (except 1) have been fixed, this is still being released as a beta. Betas also are more of a risk to your server and the data on it, but that's only if the person who programmed the script isn't a human.

Server Requirements
Here are the server requirements to run paBugs

-Linux or Windows Server*
-PHP4 or higher
-MySQL Database Access
-About 200k of space for the scripts (The data in the MySQL DB will require more space)
*paBugs has been tested on Windows 2000 and Red Hat Linux 7.1 (Both running the Apache server) It should work without a problem on Windows NT, 9x, and ME and any distribution of UNIX or Linux as well as the Micro$oft IIS server or any other web server software that supports PHP

paBugs Features
This is a list of the features in paBugs:

-MySQL Backend
-Categories and Subcategories
-Multiple Admin usernames
-Admin Center
-Admins can choose to receive e-mail notification when a new bug is reported
-Anybody can report bugs
-Reported bugs will not appear in the database until an admin approves it
-Search database
-Very easy to use

Installation
Follow these instructions to get paBugs working on your server.

1. Open pabugsconfig.php in a text editor and change the variables to how you need them. Make sure you don't remove the quotes (") or the semi-colons (;) so it still looks like this:

$variable = "value";
2. If your server requires you to use another file extension different than .php, such as .php3 or .php4 to run PHP files, follow these instructions:
	1. Rename all the files from .php to the extension you need to use, for example, .php4. Make sure you go into the pabugsadmin directory and rename those files too.
	2. Open pabugsext.ext in a text editor and replace:
		$phpext = "php";
	with the extension you need to use, for example:
		$phpext = "php4";
	or
		$phpext = "php3";
	Make sure that you DO NOT include the period before the extension. Save the file and continue to Step 3

3. Upload these files to the directory you wish to install paBugs in:
--installer.php
--pabugs.php
--pabugsconfig.php
--pabugsext.ext
--install.php
--header.html*
--footer.html*
--manual.html
--license.html
--Everything in the images directory
--Everything in the pabugsadmin directory
--Everything in the sessions directory
*Not needed if you changed the header and footer files in pabugsconfig.php
4. CHMOD the "sessions" directory 777 so paBugs will be able to write the sessions to the directory. If you are using a Windows server, you do not need to do this
5. Make sure all your settings in pabugsconfig.php for the MySQL database are correct, and run installer.php to create the MySQL tables.
6. For more security, delete installer.php from your server

Administration
Your admin center will allow you to manage your bug database

---Accessing Your Admin Center
To access your admin center, run pabugsadmin in your browser. For example, if the URL to your bug tracker is:
    http://www.mysite.com/pabugs/pabugs.php
then the URL to your admin center is:
    http://www.mysite.com/pabugs/pabugsadmin

In order to access your admin center options, you will need to login. Enter your admin username and password that you set when you installed the script, or the username and password that another admin might have created for you.

---Category Options
The category administration allows you to add, edit, delete, and recount categories.
------Add Category

This allows you to add a category to your database. Simply fill out the form and it will be added.
------Delete Category
This will allow you to delete a category from the database. Although this will not delete the bugs in this category, the bugs in this category will not be able to be viewed any more.
------Edit Category
This will allow you to change a category's name and description.
------Recount Category
If paBugs is displaying the wrong file count for a category (For example, there are 20 bugs in the category but paBugs says there are only 12) the Recount a Category will correct the count and make paBugs display the right number.

---Bug Options
The Bug Administration lets you manage the bugs in your database
------Add Bug
This will allow you to add a file to the database. Just fill out the form and the bug will be added!
------Edit Bug
This will allow you to edit a bug in the database. Once this link is chosen, a list of the bugs will show up and you can select which one to edit.
------Delete Bug
This will allow you to delete a bug in the database. Once this link is chosen, a list of the bugs will show up and you can select which one to delete.
------Approve Bug
When a user reports a bug, the bug is added as Unapproved. This means that the bug will not be displayed in the database until an admin approves it. This is to prevent people from adding a lot of worthless, fake bugs to the database.

---Admin Options
This section will allow you to add and edit all the other admins that can access the admin center. These options will only be shown if the admin who added you gave you the Admin Options privileges.
------Add Admin

This will allow you to add an admin to the DB.
------Edit/Delete Admin
This will allow you to edit or delete an admin in the database.

---Your Options
These options will allow you change your admin info or password
------Change Options
This will let you change your e-mail address and choose if you would like to receive email notification when new bugs are reported
------Change Password
If you would like to change your password, use this section. To ensure your security, you should change your password once every month.

---Other Options
There are more options available in the paBugs admin center. This section explains what they are.
------View Manual
This will show this manual you are reading right now.
------View License
This will show the paBugs license agreement that you must accept to use this script.
------Logout
This will delete your browser's cookies and log you out of the admin center. If you don't log out, you will automatically be logged out when you close your browser.

Other Features
This explains some of the other features in paBugs.

---Time Offset
You can set a time offset feature to change the time of the bugs. For example, if the server time is GMT, but you want the times on the bugs displayed in Central Time (GMT -6) you can do that. You can set the time offset in pabugsconfig.php

---Encrypted Passwords
For security, passwords in the MySQL database are encrypted using the md5 encryption algorithm. md5 is currently impossible to decrypt and won't be decrypted for a long time, if ever. Because of the encryption, DO NOT ATTEMPT TO CHANGE YOUR ADMIN PASSWORD USING A TOOL SUCH AS phpMyAdmin. Instead, you need to use the Change Password option in the admin center.
The password that is stored in your browser cookies is also encrypted.

FAQ
This section answers some of the frequently asked questions.

Q: How much does this script cost?
A: Nothing!

Q: How do I report bugs?
A: E-mail details to todd@phparena.uni.cc or use the Report Bug link on PHP Arena's own bug tracker.

Q: Can I move the copyright at the bottom of the script?
A: Yes, as long as you have the Powered by paBugs part and the link to PHP Arena and it's visible (Don't make the text white on a white background or whatever) you can move it.

Q: Will there ever be a flat-file version of paBugs ?
A: No

Q: Will there ever be a Perl or ASP version of paBugs ?
A:
---Code---
<?
$me = hate("Perl");
$me = hate("ASP");
$me = kill("Perl");
$me = kill("ASP");
$thisjoke = copied_from("paFileDB 2.0.3 Manual");
?>

---Code---
Does that answer your question?

Q: Is paBugs open source?
A: No. You are allowed to modify it to fit your needs, but it's not open source where you can do what you please with the script and release it with your name on it.

Q: My server doesn't support/allow .htaccess files, so people can view my "sessions" directory. Is this a security risk?
A: Until someone figures out how to decrypt md5 encryption (which will probably never happen) it isn't a security risk. The admin password and IP address that are stored in the session file are encrypted using md5 and probably never will be decrypted.

Q: Can I delete all those files in the "sessions" directory?
A: Yes you can. If someone is currently logged in as admin and you delete the files, all that will happen is they will be logged out and will have to log back in. In fact, you should delete the files once every week or so (Set a Cron job if possible) because the amount of files can get quite large, depending on traffic to your DB and how many times someone logs in as admin.

Q: Am I allowed to modify and distribute the script?
A: You are allowed to modify it as much as you want. As for distributing modifications, you are not allowed to distribute already-modified files, but you may give instructions on adding the modifications (Example: "On line 5, find the code ABC(); and replace it with XYZ();" or something similar is allowed)

Q: What if I do something great with the script like translate it to another language or make a flat-file version? Can I distribute that?
A: No, but if you e-mail a copy of the script to todd@phparena.uni.cc then I will be more than happy to add it to the PHP Arena file database to make it available for download and give you credit for doing whatever you did to the script.

Q: Who created all the graphics in paBugs because they're good/they suck?
A: I did. And if you think they suck, you're free to change them

Q: Why does this script look similar to paFileDB. The layout is similar and the admin center is almost exactly the same.
A: The layout of the bug tracker is totally different. The layout of the admin center is the same, but it looks nice.

Known Bugs/Issues
This explains some of the known bugs and issues with paBugs.

-The e-mail admins (who have notification enabled) receive will replace line breaks (\n or the Enter key) with <br> and put slashes (\) in front of quotation marks (")
-The graphics only look nice on white or really light backgrounds. I'll be releasing a graphics set for dark backgrounds later.
-The word "bug" is used too many times in this manual

License Agreement
Please read this whole file before installing paBugs.

paBugs is free to use and modify for almost all websites as long as you do not remove the paBugs copyright and link to the PHP Arena homepage on the bottom of scripts.

paBugs can not be used on the following types of sites:
-Warez Sites
-Hacking/Cracking Sites
-Pornographic Sites
-Any other sites that promote illegal activity

If your site is not included in that list and you keep the copyright info in the script, you may use and modify paBugs.

You may distribute paBugs as long as:
-You receive no payment for it except for costs such as internet fees (ISP, hosting, ect) and disc duplication and distribution.
-You do not modify it in any way.
-You distribute in the original zip file from PHP Arena's website (http://www.phparena.uni.cc) with all the files, including this license file.

You may use paBugs on any number of websites you like as long as all those websites are not included in the above list of websites paBugs can't be used on.

You may freely distribute any modifications you make for paBugs, but you can not distribute a whole copy of paBugs with your modifications in it. Modifications made available must contain instructions on modifying the file, not the already-modified file.

In no event will PHP Arena be liable to you for any consequential, incidental, or indirect damages (including damages for loss of business profits, business interruption, loss of business information, and the like) arising out of the use or inability to use paBugs.

If this license agreement is broken, you must cease to use and destroy any copies of paBugs you have installed.

If a PHP Arena staff member finds you breaking this agreement, s/he will send you an e-mail asking you to cease using and destroy the copy of paBugs that is breaking the agreement. You will have 24 hours after the e-mail is sent to destroy the copy. If paBugs is still up and running after 24 hours, legal action will be taken.

PHP Arena has the right to change this agreement at any time. Any changes will be posted on the PHP Arena website (http://www.phparena.uni.cc) and it is your responsibility to check for changes. If the agreement changes and then causes your copy of paBugs to break this agreement, PHP Arena still has the right to take legal action.

Other Stuff
It is against the license agreement to do one of the following things with paBugs:
-Remove the copyright at the bottom of the script
-Use it on a warez, porn, hacking, or other illegal site
-Sell it

Do you have a question that wasn't answered here? Feel free to post a message on the PHP Arena Support Forums to get an answer!

No animals or humans were harmed in the making of paBugs. Only bugs were killed, but those are software bugs that should be killed.

©2001 PHP Arena
paBugs was developed by Todd from the PHP Arena team