CodeTrack:  Bug Reporting and Tracking for the Rest of Us!


We shall close no bug before it's time...
A pain-free solution for tracking and managing code defects using a friendly web front end. Create, review and manage bug reports and developer responses for multiple projects from a common interface. Particularly suited for intranet and extranet environments, CodeTrack includes built-in strong authentication, and allows custom access control to individual projects.

If you've got a generic build of PHP and Apache, you can run CodeTrack. No database or mail server is needed. No bizarro make files! No lib-you've-never-heard-of. No Apache rebuilds or funky Perl mods. Just a modest tool for medium and small development shops, with an emphasis on open non-proprietary standards. Bug data and developer notes are stored using simple XML text files, via the built-in XML support in PHP4/5. The system runs equally well under Linux, BSD, or Windows, and it supports all major browsers.  And yes, of course, it's free.

CodeTrack is built for developers who, like us, despite having a soft spot for Open software, find themselves with feet squarely in both the *nix and Windows worlds. We all serve different masters and often wear many hats. So, if the QA folks need a no-fuss, robust tracking system, your boss needs the occasional Excel report, and you want built in scalability and data future-proofing, then give CodeTrack a try.




Features



Requirements


Data Formats

CodeTrack is a standards-compliant, cross-platform software engineering tool. We are fanatical about inter-operability, and subscribe to the "build it in right, the first time" school of thought. As such, several major data formats are available out of the box, and you are guaranteed never to be held hostage to some proprietary, vendor-specific information structure. Here are a few examples:

FAQ


Q. Why another bug tracking system? Aren't there already several mature applications that serve the same purpose?

A. There are, indeed. Bugzilla, Gnats, and Jitterbug are examples of several fine open source bug tracking systems, not to mention the plethora of commercial products such as Census Bug Track, TrackWeb, and PCVS Tracker.

The problem with most of the existing systems is that the vast majority require a dedicated database backend and full-time mail server (not to mention all the maintenance that comes along with that). In addition, nearly all require significant configuration and additions to the operating system. Case in point, take a look at the Bugzilla setup instructions. This isn't meant as a slam, incidentally, just an illustration that setup is not trivial; you really better be prepared to devote a day (or two) to the cause, and accept that there will be a significant (ongoing) amount of care and feeding for the supporting infrastructure. If you are developing a 2 million line app like Apache or OpenSSL, and need to catalog 30,000 bug reports for each branch of your codebase, then go for it -- Bugzilla will serve you well. But if you're among the mere mortals who need a little less, then take a look at CodeTrack's installation process by contrast, and decide what's best for your situation.

We would be remiss, by the way, not to mention yet another alternative. Over the past few years several Application Service Provider (ASP) vendors have also sprouted up with their version of Bug/Issue Tracking web-based systems. But frankly, the case for outsourcing this sort of thing has never been very convincing for many of us. And with the recent fall of so many promising dot coms, it seems a tough sell to buy into the give-us-all-your-data-and-trust-us model.

CodeTrack, on the other hand, requires nothing more than a plain vanilla build of PHP-on-Apache. No special libraries or mystery shared object files are needed to fill up your system directories. CodeTrack was designed to serve that niche somewhere between a small MS Access database or even an overflowing bugs spreadsheet and an industrial-strength solution like Bugzilla. Think of it as Bugzilla-Lite.

The closest open source alternative to CodeTrack is Jitterbug, used by the Samba and OpenSSL projects. We appreciate Jitterbug's less-is-more philosophy ("no Java or gratuitous graphics"), but like most of the available free bug management systems, it must a.) run as a CGI program and spawn a new interpreter process for each request, and b.) requires running Sendmail in daemonized mode. Here's a table comparing CodeTrack with several major free and commercial bug tracking applications.


Q. Why aren't you using MySQL or PostgreSQL for the backend?

A. One word. Simplicity. For the vast majority of projects, the number of bug reports would be very unlikely to ever exceed a few thousand over the lifecycle of the application (in most cases, probably more likely a few hundred). It seems to us that a full-blown relational DBMS for that level of data is a little overkill.

For the record, I am a big Oracle fan, and actually began the initial design of CodeTrack using 8i Server as a backend (using the excellent OCI library that comes with PHP). But after finishing the data model, I realized that I only needed three tables (two of which were unlikely to grow beyond 20 or 30 rows). Seemed a bit like killing a housefly with a surface-to-air missile.


Q. How many bugs can CodeTrack track?  (If a woodchuck could chuck wood...)

A. For the best response, CodeTrack was designed to normally service approximately 2,00 bugs per project, with a 10,000 bug per-project ceiling. As a practical matter, the upper bound is really a function of how much RAM and CPU you're willing to give Apache for each thread (8MB is the default, which translates in CodeTrack terms to roughly 14,000 bugs drop-dead maximum, at least out of the box). You also have to ask how acceptable, say, a 2-3 second delay is to you, in retrieving bug reports. Again, if you're Boeing and really need to catalog and manage hundreds of thousands of bug reports for millions of lines of code, this system probably won't suit you.


Q. That doesn't seem like a lot.

A. By way of comparison, we've done a little research on this topic. The SAMBA file server project has closed roughly 21,000 bugs over it's lifetime, and the entire Red Hat Linux distribution has closed about 56,000 since the company's inception. So, are 10,000 enough? In the end, only you can answer that question, based on the demands of your situation.


Q. Okay, but how is the performance of CodeTrack for real-world projects?

A. It's very fast. Customized reports, using even complex queries, are nearly instantaneous for projects with up to 1,500 bugs. <shameless_plug> For what it's worth, in collecting data for the question above this one, it took over 30 seconds to run a query and get those numbers out of their respective bug tracking systems. That may not seem like a long time, but when you're just staring at the screen waiting... </shameless_plug>.


Q. Why XML as the data format?

A. Once the decision was made that an entire database for three table just might be overkill, several standard formats were considered, including simple DBF, tab-delimited, and XML. PHP's support for DBF files is limited, and the documentation strongly recommends against write-heavy use.

I could have used a custom tab-delimited scheme, but XML is vastly more flexible. And, as one pointy-hair that I work for once observed, "The nice thing about XML is it's extensible."

Seriously though, the case for XML is a no-brainer: self-describing structure, built-in inter- operability with databases and active-content web servers, not to mention ease of editing (consider, the pain to dynamically add or move a column in a large existing comma-separated (CSV) flat file, compared to XML). Plus, it's extensible.


Q. How big do the XML database files get? I heard XML is kind of bloated.

A. In our observations, the typical CodeTrack bug report takes about 550 bytes of file space (not counting some minor overhead with the DTD header at the top of the database). So, doing the math, expect to see 1.5 to 2 MBs per 4,000 bugs. Quite respectable compared to any database like SQL Server or PostgreSQL, which would need perhaps 100 MBs of file space just for the RDBMS and setup files. You be the judge.


Q. Will CodeTrack work well with [fill-in-your-favorite-browser] ?

A. Yes! CodeTrack presents a sharp interface at all major resolutions, and has been fully tested on these browsers:
Also, CodeTrack is very friendly to tele-commuters connecting over dial-up. All pages are very lightweight (rendered size, including graphics, is between 2-10K total!). And, all CodeTrack system pages meet these rigorous standards:
Q. Will the CodeTrack app run under [fill-in-your-favorite-OS] ?

A. Most likely! We have either first-hand experience or reputable direct reports of the system running under these operating systems and Apache/PHP engine combinations in production settings (many other configurations are no doubt possible, but these have been verified): Note: Although not CodeTrack specific, there are known issues running PHP with Apache 2.0, due to threading problems in third party libraries, so tread carefully if using in a production environment. See this thread on the Core PHP developer list for more history. Also straight from the horse's mouth (i.e., the install guide on php.net): "We do not recommend using a threaded MPM in production with Apache2. Use the prefork MPM instead, or use Apache1."

If you have a success story you'd like to share, please mail us; we'd be delighted to hear from you.


Q. Are any special XML libraries or RPMs required?

A. No. The default PHP build already includes the XML functions needed (note - CodeTrack does not require the experimental XDOM libraries; instead it depends on the Expat routines). Unless you went out of your way to specifically exclude the XML library during the modPHP make process, things should just "automagically" be there. If you're completely paranoid, a quick little <?phpinfo();?>  can confirm whether Expat is in place. Look for "XML Support" -- if it's listed as "Active" you're set. If it's not, most likely you're running PHP version 3.x.


Q. Is CodeTrack secure?

A. It depends. Every reasonable measure has been taken to sanitize form data (especially screen print attachment uploads), but a formal security audit has not yet been completed. CodeTrack is ideal for in-house (i.e., intranet) environments. If you decide to run this on a public server, you are strongly urged to run Apache in SSL mode, and limit access to a known group of users via the built-in MD5 authentication mechanisms. Like any active-content web application, (e.g., ASP, Cold Fusion, traditional CGI), there is always some degree of risk for denial of service attacks by bombarding the web server repeatedly with resource-draining requests, mal-formed page requests, embedded shell escape characters, and form POST buffer overflows, so proceed with caution. Remember, most hacks are done by exploiting applications in very non-intuitive ways. So, don't be surprised if you ignore these warnings, run CodeTrack naked on a publicly exposed server, and one morning discover that, not only have you been rootkit'ed, but also have the joy of explaining to the boss precisely why there are 2 gigs of fresh pornography in the attachments directory, and thousands of download requests referred from warez.com in your access logs!

CodeTrack intentionally includes unforgiving authentication checks in the first few lines of execution. Should credentials be missing or fail, a redirection is forced to the login page. No GET-style requests are permitted either for either login or posting a new or modified bug. But, we cannot emphasize enough, if you disable authentication, or give out "one-size-fits-all" passwords to users, and run CodeTrack in public web space, you are insane.


Q. Why does CodeTrack use cookies? Cookies are evil. Just another way for The Man to monitor our every move.

A. Yes, and cattle disappearances are on the rise too. Seriously, though, because HTTP is a stateless protocol, the options for managing active-content sessions between pages are limited. Let's look at our options - traditional HTTP authentication (i.e., Apache htaccess/PHP_AUTH_USER), ala Lotus Notes. The main problem with this approach is that passwords are sent to the web server in plaintext for every page request. If SSL is not used, a number of freely available sniffer tools would be happy to collect your users' passwords via CONTENT headers passed prior to every page request. Did we mention that every page request would transmit the plaintext password?

Option 2. Session IDs via Javascript or hidden frame variables. This technique is used often and can be a workable solution in some applications. The major drawback is that each page request requires the client-side agent to store and update all session variables, and either append it to every traditional link(i.e., page?foo=bar&session_id=ABC), or in the case of form posts, add it as an explicit or dynamic hidden variable to be sent as part of the submit. While these issues are manageable, the biggest headache to the variable-in-frame technique has to do with user behavior, specifically the back and forward buttons. Once the entire frameset is part of the browser history(i.e., not the currently displayed page), all bets are off with respect to variable state. When the user navigates back, maybe frameset variables are the way they were set when the frame first loaded, or maybe they are exactly as they were on last viewing. It's completely browser-dependent. And, surprise, surprise, the current crop of major browsers all behave completely differently. Anything other than the most trivial dynamic applications are thus wed to vendor-specific hacks, or have to take more draconian measures like disabling navigation buttons. The only other option? Cookies. Full circle, huh?


Q. But can't Apache or PHP automagically handle sessions and related authentication?

A. No such thing as a free lunch. Read the fine print, and you'll see that what's actually being used are either cookies or on-the-fly URL translation. The only difference is that the web server manages session information and page variables with ad hoc centrally-managed files.

One of CodeTrack's main design goals was simplicity. Forgetting for the moment the known issues with proxy servers, stateful packet firewalls and "lost" URL sessions, honestly, how many medium- and small-traffic folks would read too much further if the install instructions began with, "First, grab the latest modRewrite from foo.org, then re-compile Apache, then create htaccess files, then overhaul httpd.conf..."   I know I would have tuned out.


Q. Okay, so cookies it is. I noticed you set them with Javascript rather than the traditional HTTP header method. Why?

A. At the risk of inciting religious wars, the answer is, there is no single technique to set cookies server side which works cross-browser and cross-platform. What's my evidence for such a bold claim? See the very interesting site here. These guys have collected the best empirical numbers on the topic that I've seen. They have tested 11 different server-side techniques on over 10,000 unique hits (IPs), for visitors to a major public (adult) web site, amassing 50MBs of test logs. The audience represents a mix of nearly every browser and every OS out there. It turns out that client-side Javascript cookies worked over 98% of the time, versus 60-80% for other methods. It also turns out that Netscape, Opera, Mozilla, and IE all require slightly different header strings on server-set cookies, but, oddly enough, all apparently do comply with Javascript 1.1, pretty much regardless of platform or browser (so much for RFC guideline standards...) And, by the way, this is true even within same-vendor products (see the newsgroups about the cornucopia of methods used by the many IE flavors on different operating systems, especially XP and the Mac, not to mention IE 4 versus 5.5 versus 6...). For real pleasure reading, take a look at the user-annotated PHP manual on this topic. In a perfect world, we would have abandoned Javascript in CodeTrack, except maybe for some net-friendly form validation, to save unnecessary trips to the server, but you can't argue with success. Javascript 1.1 is supported (here, remarkably consistently) on every major contemporary browser. So, there we are...



The Code

The latest code is always at our SourceForge site



Installing CodeTrack 

  _____________________________________________________________

       A 5 minute guide to installing CodeTrack v.0.99
         (FIRST TIME only; existing users, see below)
  _____________________________________________________________


In a nutshell:  copy files to Apache-owned space, set permissions, specify a return e-mail
address, and go.


 1. Create a directory in the htdtdocs root space, for example:

    mkdir  /home/httpd/htdocs/codetrack


 2. Unzip and untar the codetrack files to this directory:

    tar -xzvf codetrack.tar.gz /home/httpd/htdocs/codetrack

    (Windows users can use Winzip, either on the *.gz or *.zip release)


 3. Set the permissions for the directory so that it is readable and writable by
    the apache owner:

    chown -R nobody.nobody /home/httpd/htdocs/codetrack
    chmod -R 600 ` find /home/httpd/htdocs/codetrack -type f `
    chmod -R 700 ` find /home/httpd/htdocs/codetrack -type d `

    (Windows users can do the same thing through the GUI, just make sure the XML
    files and the attachments directory are writeable.  You may have to set the
    ownership to Administrator.  Thanks, Microsoft!)


 4. To use e-mail notification, edit codetrack.php and set a real return address for codetrack:

    change: DEFINE ("CODETRACK_RETURN_ADDRESS", "me@localhost.localdomain" );

    to:     DEFINE ("CODETRACK_RETURN_ADDRESS", "CodeTrackAdmin@myCompany.com" );

    or:     DEFINE ("CODETRACK_RETURN_ADDRESS", "DoNotReply@foo.org" );


   To *DISABLE* e-mail in CodeTrack, edit codetrack.php, and set
      CODETRACK_ENABLE_EMAIL to FALSE

    ___________________________________________________________________________

    SPECIAL NOTE TO PHP-ON-WINDOWS USERS ONLY:

       If you've never used the PHP mail functions on your web server before, edit
       the php.ini file and set the options below.  Note that you might be able
       to use your ISP's SMTP server if you don't have one.  The box running PHP
       does NOT have to be running a mail server (i.e. Exchange) for this to work.

       php.ini:

          SMTP       =  localhost            ;for win32 only
          sendmail_from =  me@localhost.com  ;for win32 only

            to:

          SMTP       =  mailserver.foo.org    ;for win32 only
          sendmail_from =  bob@foo.org        ;for win32 only

     You will need to stop and restart Apache for the changes to take effect
    ____________________________________________________________________________


 5. Fire up a browser and navigate to  server-name/codetrack/


 6. Initially, login as the System Admin:

    login:   admin
    pw:      codetrack
    project: Test Project

    After logging in, change your password, set up a few users and your initial
    "real" project, and go!



                      THAT'S IT!



   If you get stuck, please re-read this document, and check
   SourceForge bug report, but feel free to write us at:  codetrack@openbugs.org



  _____________________________________________________________

       A 5 minute guide to UPGRADING to CodeTrack v.0.99.3
               (For existing v.0.99.2 users ONLY)
  _____________________________________________________________


In a nutshell, four basic steps:  run a backup from within CodeTrack,
directory, copy your existing xml data files and config.inc.php configuration
somewhere safe, Untar/zip the v.0.99.3 files to a temp directory (NOT your real
htdocs location!) and then replace your exising codetrack.php and config.inc.php
with the the new codetrack.php and config.inc.php files from the v.0.99.3
release, but *only* these two files.  Set permissions, and you're ready to go.


                   ***  CRITICAL NOTE  ***

     Do NOT unzip the new files to your working codetrack
     directory, or you will overwrite your existing data with
     empty bugs, users, and projects files!!!



 1.  Run a backup of your existing xml files:

     In Codetrack:  Admin/Backup XML Databases/Backup Now


 2.  Copy your current xml files and configuration file somewhere safe:

     cp /home/httpd/htdocs/codetrack/backups/*xml* ~/somewhereSafe/
     cp /home/httpd/htdocs/codetrack/config.inc.php ~/somewhereSafe/
     ls ~/somewhereSafe/
     (Windows users: the key here is that these are your *current* files, not the ones
      just downloaded)


 3.  Untar/unzip the updated codetrack.php and config.inc.php files to your web directory:

     tar -xzvf codetrack.tar.gz ~/tempDir (Windows users just unzip to a temp directory)
     cp ~/tempDir/co*php   /home/httpd/htdocs/codetrack


 4. Set the permissions for the directory so that the two new files are readable writable by
    the apache owner:

    chown -R nobody.nobody /home/httpd/htdocs/codetrack/co*php
    chmod -R 600 /home/httpd/htdocs/codetrack/co*php

You might want to diff the two config.inc.php files if you've made any tweaks,
otherwise, the defaults should Just Work(tm).
If you get an error when trying to start CodeTrack, the first thing to verify is a simple sanity check that you can view a known document with your browser on the same server, i.e., http://name-of-your-sever/foo.html   Next, verify that PHP is behaving in the directory where CodeTrack lives. Try creating a dummy test file like this:

     <? phpinfo(); ?>

Save it as something like "foo.php" in the CodeTrack directory, and see if you can view that (should dump lots of system and diagnostic information). If this doesn't work, then you've got bigger problems. Check your Apache setup, and if necessary run the installer again and really pay attention to the questions is asks. 99% of problems with starting CodeTrack are caused by improper Apache setup, or erroneous permissions or file ownership. You can also look at TROUBLESHOOTING.txt for more troubleshooting advice.



CodeTrack Support

The Top 5 CodeTrack Support problems (and solutions):

1. If you are seeing a horrible looking white login screen with huge default Times Roman fonts, your permissions on the style (and likely all other) subdirectories is wrong. See INSTALL.txt, but the short version is that the Apache owner needs read+write+execute on several directories, and read+execute on ALL directories under codetrack.

2. If you are having mail problems, review INSTALL.txt and TROUBLESHOOTING.txt. Also take a look at www.php.net/manual/en/function.mail.php and try the first or second example as a simple sanity check that ANY outbound mail will work with your PHP webserver. If the one-liner at PHP.net isn't working, there is no way CodeTrack will work.

3. If you find a really broken screen that includes PHP error messages about "Headers already sent" -- the real problem is in the source code line number. Typically this is seen when trying to send mail on a Linux box where no outbound mail agent exists, or a broken Windows SMTP setting in php.ini.

4. If you are using Windows and trying to run CodeTrack on IIS, as laid out in the Requirements section above, CodeTrack has two simple needs: Apache and PHP. Because it relies on Apache-specific server variables, it WILL NOT work with IIS. If you have a desperate need to run CodeTrack as an IIS CGI, by all means, Use the Source and submit a patch!

5. If you are seeing strange problems with export downloads, verify that any mods you made to either codetrack.php or config.inc.php did not accidently add new lines above or to the right of the opening and closing php tags (yes, literally a few extra spaces at the end of the file will cause IE to "outsmart" the proper MIME format, and try to parse a file as raw HTML.




Contact Us

If you have questions or comments, e-mail codetrack@openbugs.org. And, please God, provide these basic data: OS version, Apache version, PHP version, browser -- example: MacOSX 10.4, Apache 1.34, PHP 4.36, Opera 8.0   (not trying to be a pain -- we *really* want to help, but we're pretty blind without this information).   Also, please be sure to include the word "CodeTrack" in your subject line, so you're not filtered out as spam!



The CodeTrack License


CodeTrack is released under the GPL copyright 2001-2006 by Kenneth White

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.









CodeTrack is best viewed with any browser!

Valid HTML 4.01!       Valid CSS!