WISE 1.0 Alpha Release


This file describes the Web Integrated Software Project Management and Metrics Tool (WISE) (patch level 0) for Solaris 2.X Copyright © 1995 John R.Callahan, Sudhakar Ramakrishnan, Wei Sun, and Nicholay Gredetsky.

WHAT IS WISE?

The Web-Integrated Software Environment (WISE) is the first WWW-based project management and metrics system available on the World-Wide-Web. WISE is a WWW-based tool that provides a framework for managing software development projects across the Web. WISE allows programmers and managers to log issue reports, track the status of issues, and view project metrics using standard WWW browsers. WISE issue forms, reports, roles, responsibilities, and metrics can be customized for an organization. WISE provides a non-intrusive method to coordinate project activities and allow software development teams to view their progress and performance.

WISE QUICK INSTALLATION

To run a minimal WISE server you will need to first install (1) an http server (NCSA httpd 1.3 or higher) and (2) the mSQL database package (version 1.0.7 or higher). You must build WISE on your WWW server host (the WISE cgi binaries must be co-resident on the WWW server). While the project database(s) may reside on other hosts, the WISE binaries need to be compiled and linked with mSQL client libraries. After the NCSA httpd and mSQL packages are installed, follow the steps below:

  1. Download the WISE 1.0 Alpha distribution.
  2. Decompress (using gunzip) and untar the distribution file. This will create a directory called wise-1.0 in the current directory.
  3. Set your LD_LIBRARY_PATH environment variable to include the UCB compatibility libraries (usually in /usr/ucblib).
  4. Examine the file conf/site.wpl.in and check the value of the PORT number. The default is 80 (the standard WWW server port). If your port is different, you may change this now or later. You may also decide to hard code in the HOST name for you WWW server at this time. The rest of the fields will be handled by the configure process.
  5. Change directory to the new wise-1.0 directory and type make in this top level directory. You will prompted by the WISE configuration script for the path of the htpasswd binary and the MSQL distribution binaries (msql, msqladmin, msqldump), library (libmsql.a) and include files (msql.h). If you want to install the software metrics package, you will also be prompted for paths to gnuplot and pbmplus tools (ppmtogif and ppmquant). You can install the metrics tools later (see the Reconfiguration section below). Also, you will be asked to supply a password for the user name anonymous during the make process. WARNING: If you answer yes to the question to initialize the .htaccess file, then the old .htaccess file will be erased! When first installing WISE, answer yes.
  6. Edit the srm.conf file on your NCSA http server and add the lines (where PREFIX is the parent path of the WISE installation directory):
  7. Restart your WWW server so that it will reread the srm.conf file (e.g., send it a HUP signal).
  8. This process will create a fully operational, demo version of WISE at your site. You can connect to it with a WWW browser that supports tables (e.g., Netscape version 1.1 or higher) via the address of your WWW server (e.g., www.foo.com) as: http://www.foo.com/wise-bin/tdl.
  9. This demo WISE server uses the MSQL server at OUR distribution site (research.ivv.nasa.gov) as the database backend. If WISE does not work, check the conf/site.wpl file in the wise-1.0 directory and check the HOST and PORT settings. Edit these values if they are incorrect, save the file, and type make again in the top level wise-1.0 directory.

CUSTOMIZING WISE FOR YOUR ORGANIZATION

To customize WISE issue forms and roles for your organization, follow the steps below. Edit the conf/site.wpl file. Make sure that the HOST and PORT values are correct for your WWW server. For example, to add a user "smith" to the "Widget" project as a "developer", add the line:

ROLE smith ISA developer ON PROJECT Widget;

to the conf/site.wpl file. See the doc subdirectory for information on the WISE Programming Language (WPL).

  1. Type make in the top level directory. This will build the include/wise.h file and the cgi binaries.
  2. Type make users in the top level directory. This will ask you to provide a password for all people in your organization. WARNING: If you answer yes to the question to initialize the .htaccess file, then the old .htaccess file will be erased!
  3. Type make databases to initialize any databases. It will run msql scripts to create and initialize the databases you specified in the conf/site.wpl file. An msql database will be created for each project in the conf/site.wpl file. *** WARNING *** This step will ask you if you REALLY want to initialize each project database. If a database already exists, then all records will be lost! See the instructions below for making subsequent changes to the conf/site.wpl file.
  4. Copy (or merge) the automatically generated conf/msql.acl file into the msql.acl file in the top-level directory of your MSQL installation directory. This is the access control file for the MSQL. It assumes that you run the NCSA httpd as nobody from the current host. An entry is created for each database created (a WISE project corresponds to a database) that allows nobody to read and write each project database from the WWW server host.

MAKING CHANGES

If you need to make changes to your conf/site.wpl file after the initial definition of your projects because projects, people, roles, and issues forms have changed, then:

  1. Change directory to the wise-1.0/dumps subdirectory
  2. Run ../bin/dumpit to create a set of dump files (see Dumping section below).
  3. Edit the conf/site.wpl file and make the necessary changes.
  4. Type make in the top level directory. This will build the include/wise.h file, the WISE cgi binaries, and new database initialization and dump scripts.
  5. Hand edit the MSQL dump files and change the MSQL table creation and insert directives to accommodate the database changes. Currently, we do not have an automated method for editing existing databases.
  6. Update each project database by submitting the edited dump file (for each project project on the date YY-MM-DD) via the msql client tool using the command: msql -h host project < project-YY-MM-DD.msql

If NEW people or projects were added in the conf/site.wpl file, you must also execute the following steps:

  1. Type make users in the top level directory. This will ask you to provide a password for all people in your organization. WARNING: If you answer yes to the question to initialize the .htaccess file, then the old .htaccess file will be erased!
  2. Type make databases to initialize any databases. It will run msql scripts to create and initialize the databases you specified in the conf/site.wpl file. *** WARNING ***: Answer NO when asked to initialize existing databases.
  3. Check the newly generated conf/msql.acl for any new entries and merge them into the msql.acl file in your top-level MSQL installation directory.

METRICS

To install the metrics package after initial installation, install the following packages:

  1. pbmplus - the ppmtogif and ppmquant tools
  2. gnuplot - with time extensions and filled histograms

and then type make config in the top-level WISE directory. Answer the questions regarding paths to the mSQL package, pbmplus, and gnuplot. After you have installed the gnuplot and pbmplus tools, type make metrix in the top level directory. At some point, you may want to run the metrics commands periodically from a crontab file.

DUMPING

You can snapshot ALL project databases for purposes of backing up or restoring in case of problems. You must patch the standard MSQL program with the patch that allows for named SQL inserts.

To dump the WISE project databases, change to the wise-1.0/dumps directory and run the command dumpit which will create a dated dump file (project-YY-MM-DD.msql) for each project. A dump file can be used subsequently to restore a database using the command:

msql -h host project < project-YY-MM-DD.msql

It is especially helpful to update the msqldump program with the patch that allows for named inserts. This permits a reload of the old database into a new schema without editing each SQL insert command from the dump. Here's the patch:

From owner-msql-list@kirk.Bond.edu.au  Wed Aug 23 06:31:09 1995
Received: from pmlsun.cacs.usl.edu by console.cacs.usl.edu with SMTP id AA28034
  (5.65c/IDA-1.4.4 for ); Tue, 22 Aug 1995 15:27:41 -0500
Date: Tue, 22 Aug 1995 15:27:41 -0500
From: "Patrick M. Landry" 
Message-Id: <199508222027.AA28034@console.cacs.usl.edu>
To: msql-list@Bond.edu.au
Subject: [mSQL] small enhancement request
X-Sent-To: msql-list
Sender: owner-msql-list@bond.edu.au
Precedence: bulk
Reply-To: msql-list@Bond.edu.au


Hi David,

Thanks for a great tool. I have a tiny enhancement request that I
think others would like also. I have already implemented it here.

In order to add a field to an existing database currently I use msqldump
then edit the resulting file and recreate and reload the database. The
problem is that I have to manually add a new field to all the INSERT
commands as well as to the CREATE command. The small change I have made
is to have msqldump print out all the field names in the INSERT commands
when it produces its output.  That way all I have to do is add the field
to the CREATE command.

I am appending a context diff which has my (3 line) change to msqldump.c

Thanks again
--
patrick

*** msqldump.c.orig     Tue Aug 22 15:08:12 1995
--- msqldump.c  Tue Aug 22 15:19:31 1995
***************
*** 165,171 ****
        }
  
        printf("\n#\n# Table structure for table '%s'\n#\n",table);
!       sprintf(insert_pat, "INSERT INTO %s VALUES (", table);
        printf("CREATE TABLE %s (\n", table);
  
        while(mf=msqlFetchField(tableRes)) 
--- 165,171 ----
        }
  
        printf("\n#\n# Table structure for table '%s'\n#\n",table);
!       sprintf(insert_pat, "INSERT INTO %s (", table);
        printf("CREATE TABLE %s (\n", table);
  
        while(mf=msqlFetchField(tableRes)) 
***************
*** 177,184 ****
--- 177,186 ----
                else
                {
                        printf(",\n");
+                       sprintf(insert_pat, "%s,", insert_pat);
                }
                printf("  %s ", mf->name);
+               sprintf(insert_pat, "%s%s", insert_pat, mf->name);
                switch(mf->type) 
                {
                        case INT_TYPE:
***************
*** 202,207 ****
--- 204,210 ----
                        printf(" PRIMARY KEY");
        }
        printf("\n) \\g\n\n");
+       sprintf(insert_pat, "%s) VALUES (", insert_pat, table);
        numFields = msqlNumFields(tableRes);
        msqlFreeResult(tableRes);
        return(numFields);

RECONFIGURATION

To reconfigure WISE (i.e., add the metrics packages or point Makefiles to new paths for msql, gnuplot, and other needed programs), then type the command make clean then the command make config in the top-level WISE directory. You will be asked for the new paths of programs during the make config process. WARNING: Doing a reconfiguration will overwrite your site.wpl file. Delete the site.wpl.in file or edit the site.wpl.in file to avoid this problem.

MORE ON WISE

After the flood of initial interest in WISE, we had to make some strategic changes to our development plans. We apologize for the 2 month slip in scheduled release of WISE, but we want to release a usable, well-tested tool. After making major changes to the WISE implementation, we have been using WISE internally for the last 2 months to manage our own projects. Some features of the new WISE implementation include:

Easy Configuration - we have developed a programming language for configuring WISE. To customize WISE for your organization, you only need to change a single configuration file. Also, we have added MANY new field types including html fields, selects, multi and single radio buttons, log fields, and more!

Extensible Metrics - we have developed a modular metrics package that allows for the addition of new metrics analysis in the future. In addition to the current histograms, we will also release a trend plot, Gantt chart, and trend analysis packages.

Based on a Public-Domain Database Package - under actual use of the previous version of WISE, we had some performance problems with the Oracle database backend (nothing about Oracle in particular, but mostly because it was overloaded at our site by other projects). We reimplemented WISE on top of the David Hughes mSQL database package. This improved performance and makes WISE usable by man more organizations.

Better Performance - Thanks to mSQL, WISE runs much faster at our site. Based on our measurements, we achieved an order of magnitude increase in display of To-Do Lists and individual issues.

The purpose of the WISE project is to demonstrate the viability of metrics collection and use in our projects. Our project was inspired by the Experience Factory work by Basili, McGarry and Pajersky at the NASA Software Engineering Laboratory (SEL). WISE was developed as a "practice what you preach" approach to getting software organizations to collect and use metrics in the management of small and large scale software development efforts.

The WISE project is sponsored through a cooperative agreement between the NASA Software IV&V Facility in Fairmont, West Virginia and the Concurrent Engineering Research Center (CERC) at West Virginia University in Morgantown, West Virginia. (C) Copyright at West Virginia University. All Rights Reserved.

COPYRIGHTS & DISCLAIMER

WISE [both binary and source] (hereafter, Software) is copyrighted by John R.Callahan, Sudhakar Ramakrishnan , Sun Wei and ownership remains with the authors.

The authors grant you (hereafter, Licensee), a license to use the Software for academic, research and internal business purposes only, without a fee. Licensee may distribute the binary to third parties providing that the copyright notice and this statement appears on all copies and that no charge is associated with such copies.

Licensee may make derivative works. However, if Licensee distributes any derivative work based on or derived from the Software, then Licensee will (1) notify the authors regarding its distribution of the derivative work, and (2) clearly notify users that such derivative work is a modified version and not the original WISE tool distributed by the authors.

Any Licensee wishing to make commercial use of the Software should contact the authors to negotiate an appropriate license for such commercial use. Commercial use includes (1) integration of all or part of the source code into a product for sale or license by or on behalf of licensee to third parties, or (2) distribution of the binary code or source code to third parties that need it to utilize a commercial product sold or licensed by or on behalf of Licensee.

THE AUTHORS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE AUTHORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY USERS OF THIS SOFTWARE.

By using or copying this Software, Licensee agrees to abide by the copyright law and all other applicable laws of the U.S., including but not limited, to, export control laws, and the terms of this license. The authors shall have the right to terminate this license immediately by written notice upon Licensee's breach of, or non-compliance with, any of its terms. Licensee may be held legally responsible for any copyright infringement that is caused, directly or indirectly, by Licensee's failure to abide by the terms of this license.

Direct notices to:

John R.Callahan
886 Chestnut Ridge Road
Concurrent Engineering Research Center
West Virginia University
Morgantown, WV 26505
USA
phone: (304) 293-7226
email: callahan@cerc.wvu.edu