Midge - a simple but powerful bug tracking system

   Copyright(C) 2003 Timothy Corbett-Clark <tcorbettclark@users.sf.net>

   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, 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.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   For more details see the file COPYING.


Requirements
============
 
Midge has been developed and tested with the following software
(earlier versions may work):

   postgres-7.4.2
   psycopg-1.1.11
   python-2.3.3
   egenix-mx-base-2.0.4


Install
=======


 1) Adjust setup.py as required.

 2) Build:

      python setup.py build

 3) Install:

      sudo python setup.py install

 4) Edit configuration file:

     vi /etc/midge.conf

 5) Setup the databases (one for real, one for testing)

     sudo midge-admin setup

 6) Adjust configuration of postgres.

    The simplest (but not safest) approach is to edit (as root)

       /var/lib/postgres/data/pg_hba.conf

    changing the line for "All other connections by UNIX sockets" from
    method "ident sameuser" to "trust".

    Don't forget to restart postgres, e.g.

      sudo /etc/init.d/postgresql restart

 7) Run tests:

     midge-test

 8) Start:

     midged &

    (as an ordinary user)

 9) Point your browser to http://localhost:8000
    (or as per the config file).


Importing/exporting bugs
========================

There are two commands:

   midge-import <users_filename> <bugs_filename> <comments_filename>

and

   midge-export <users_filename> <bugs_filename> <comments_filename>

This uses 3 csv files to store the complete state of the bug database.

The columns of these csv files have titles; the easiest way of finding
out the format is to start midge, enter a few bugs, and run
midge-export...


Logging
=======

By default, logging information is sent to the syslog daemon (port
514) on localhost under the DAEMON facility. Both the host and the
facility are configurable (see /etc/midge.conf).

Note that you will need to have UDP logging switched on, typically by
passing "-r" to syslogd.

More verbose logging may be switched on by setting "debugging: yes" in
the Logging section of /etc/midge.conf.

Adding users and passwords
==========================

Midge is intended to be used in a trusted environment. Anyone can add
a new user account, and if you forget your password it will be emailed
to you in the clear. So the password is not about security but about
preventing accidents (e.g. selecting the wrong username on login).

So don't use a secure password.

For the same reasons, passwords are not hashed in the underlying
database.

States
======

Approach:

  - Keep the number of states to a minimum so that the user can easily
    make queries, without accidentally missing bugs.

  - Don't have state values which are rarely used (e.g. use "new"
    again, rather than "reopened")

  - Keep states as orthogonal as possible. So for example, don't have
    a resolved category which is only relevant when the status is
    closed or fixed. Also don't allow multiple "fixed in versions" as
    this clashes with the status (use separate bugs linked through
    keywords).

  - Allow some states to have values dynamically decided by the user
    (and automatically cleaned up when unused).

  - All underlying tables (and separate user-enterable fields) are
    justified by the need for searching; do not store purely
    informative data in separate tables, and avoid the user needing to
    enter them using separate fields. For example, although it is
    useful to know which machine a bug occured on, it is most unlikely
    that one would need to search on this.

The key state variable is the "status":

  new		a new unread (or reopened) bug
  reviewed	acknowledged useful entry, but don't fix yet
  scheduled     ready to be fixed now
  fixed  	believed fixed (or not a bug), but to be confirmed by testing
  closed	confirmed fixed (or not a bug)

  Note that all new bugs start as new. Typically, Managers take new to
  reviewed or cancelled, and to scheduled if ready to fix; Developers
  take scheduled to fixed, tackling them in order of priority;
  Testers take fixed to closed, cancelled, or new.