File: README-PHASE-5

Contents:

1. Quick install
2. How it works?
  2.0. Functional capabilities.
  2.1. Technical support request.
    2.1.1. "categories" configuration file
    2.1.1. "accounts" configuration file
    2.1.2. "products" configuration file
    2.1.3. "supercategories" configuration file
    2.1.4. ACCOUNT_ID authentication
    2.1.5. Example
    2.1.6. "VISA" authentication
  2.2. Billing information encryption & decryption
  2.3. Billing status upgrade
  2.4. Submission follow-up information
  2.5. Requesting patches
    2.5.1. Submission patches
  2.6. Technical support rating
    2.6.1. Rating summary retrival
3. WWW GNATS


    1. Quick install

1.1. Get and untar gnats-3.104-beta:
        tar xfz gnats-3.104-beta.tgz
or
        gzip -dc gnats-3.104-beta.tgz | tar x

1.2. Untar patch:
        gzip -dc gnats-phase-5.tgz | tar x

1.3. Apply patch:
        patch < gnats-phase-5-patch

1.4. Make GNATS:
        cd gnats-3.104-beta
        ./configure --with-full-gnats

     Adjust CVS and CVS_ROOT variables to your settings in gnats/Makefile.

        make all
        make install
        cd ..

1.5. Make auth-pr (stub for charge authorization program):
        cd auth-pr
        cc -o auth-pr auth-pr.c

     If you had changed $GNATS_PREFIX setting then
	cp auth-pr cards $GNATS_PREFIX/libexec/gnats
     otherwise
        cp auth-pr cards /usr/local/libexec/gnats

        cd ..

1.6. Go to wwwgnats directory:
        cd gnats-3.104-beta/gnats/contrib/wwwgnats

1.7. Unshar wwwgnats:
        ./wwwgnats.shar

1.8. Apply patch:
        patch < ../../../wwwgnats-phase-5-patch

1.9. Copy wwwgnats utils
        cp bin/* /usr/local/bin

1.10. Customize and copy cgi-scripts:
      In pr.pl
      ...
      $cgi_dir = "/usr/lib";
      $cgi_subdir = "/cgi-bin";
      ...
      set $cgi_dir to the directory containing your site cgi-bin
      directory, set $cgi_subdir to real name of your site cgi-bin
      directory. If you are not sure, ask your www administrator.
       
      In libgnats.pl
      ...
      $GNATS_BIN  = "/usr/local/bin"; # must be on nc
      $GNATS_LIB  = "/usr/local/libexec";
      $GNATS_ROOT = "/usr/local/share/gnats/gnats-db" unless $GNATS_ROOT;
      $GNATS_ADM  = "$GNATS_ROOT/gnats-adm";
      $PR_EDIT    = "$GNATS_LIB/gnats/pr-edit";
      $PR_ADDR    = "$GNATS_LIB/gnats/pr-addr";
      $GNATS_VER   = "3.2";
      $GNATS_ADDR  = "bugs";
      ...
      set the above listed variables according to your GNATS settings.
       
        cp cgi/*.pl your-site-cgi-bin-directory


1.11. Configure GNATS according to its documentation.
      (mkcat, gen-index, ...)


    2. How it works?

2.0. Functional capabilities.

Submitter may claim technical support for his problem
report by suppling his billing information together with
the report ("send-pr") or by providing his billing information
later with "upgrade-pr" utility or through WWW GNATS interface.

Submitter may provide follow-up information for his
previous problem report with "upgrade-pr" utility.

Submitter may request the patch for a "closed" or "feedback"
problem report with "request-patch" utility.

Submitter may fill out technical support rating reports
where he appreciates technical support for the problem
report (commercial technical support call) he had supplied.
The utility "rating-pr" is intended for providing that
capability.

Utility "mkdist" which prepares GNATS client distribution
is extended to insert GNATS client distribution "upgrade-pr",
"request-patch" and "rating-pr" utility.

Utility "edit-pr" adds a record into rating files
($category/.rating) when the problem report state under
edition is changed to "closed".

Utility "rating-sum" was added to GNATS administrator
distribution. The utility makes reports for "closed"
reports and technical support rating for the specified
time period.

2.1. Technical support request.

Submitter may claim technical support for his problem report
by providing his billing information in "send-pr" form in the
field ">Billing-Info:".

The following billing information is accepted:
  ACCOUNT_ID  LLLLLLLLL
  VISA XXXX XXXX XXXX XXXX

  L - letter or digit (except for '|', ':')
  X - digit

If supplied billing infromation is valid then
responsible persons notified the fact.

If billing information can not be verified immediately
then the verification is postponed and is performed later
by GNATS administrator.

In either case the submitter is notified the result.

2.1.0. "categories" configuration file

"categories" configuration file now includes additional field:
the list of releases available at CVS repository.
The list is checked when a patch request for the category
is processed.

2.1.1. "accounts" configuration file

"accounts" configuration file is used to store accounts of
the registered users. "accounts" file is located where the
others GNATS configuration files do. The file has the following
format:

submitter-id:account-id:response-time:list-of-products

submitter-id	- the submitter e-mail address
account-id	- the unique submitter account identifier which
                  should be supplied in technical support requests
                  in ">Billing-Info:" field
response-time	- response time in business hours (like in "submitters")
list-of-products- "|" - separated list of products, supercategories and
                  categories registered for the submitter.

2.1.2. "products" configuration file

"products" configuration file is used to store definitions of products.
"products" file is located where the others GNATS configuration files do.
It has the following format:

product-id:list-of-supercategories

product-id	- the unique identifier of the product (e.g., Yggdrasil)
list-of-supercategories
		- "|" - separated list of supercategories and categories

2.1.3. "supercategories" configuration file

"supercategories" configuration file is used to store groups of
categories united in supercategories. "supercategories" file is
located where the others GNATS configuration files do. The file
has the following format:

supercategory-id:list-of-categories

supercategory-id
		- the unique identifier of the supercategory
list-of-categories
		- "|" - separated list of categories

2.1.4. ACCOUNT_ID authentication

If submitter had supplied ACCOUNT_ID LLLLLLLLLL then the
"accounts" configuration file is checked for the inclusion
the record:

submitter-id:MMMMMMMMMM:XX:list-of-products

If the record beginning from the submitter-id supplied in
problem report is found then LLLLLLLLL is compared to
MMMMMMMMMM and if they turn out to be the same then the
category is checked for inclusion in the list of products.
That is, products are expanded into supercategories and the
latters are expanded into categories and the category supplied
in the problem report is checked to be in the resulting
list of categories.

2.1.5. Example:

Submitter had supplied the problem report:

...
>Submitter-Id:  john@aol.org
>Category:	gcc
>Billing-Info:	ACCOUNT_ID AS45
...

"accounts"
...
john@aol.org:AS45:10:Yggdrasil|SSL|PGP
...

"products"
...
Yggdrasil:Base|X-base|gdb
...

"supercategories"
...
Base:kernel|gcc
X-base:X-server|X-free86
SSL:ssl-in|ssl-out
...

"categories"
...
kernel: ...
gcc: ...
gdb: ...
X-server: ...
X-free86: ...
ssl-in: ...
ssl-out: ... 
PGP: ...

GNATS checks john@aol.org in "accounts". It is Ok. Thereafter
GNATS compares "AS45" supplied in PR  and "AS45". They are
the same. Then GNATS expands "Yggdrasil|SSL|PGP" from "accounts"
into "kernel|gcc|X-server|X-free86|gdb|ssl-in|ssl-out|PGP" and
checks whether the category supplied in PR (gcc) in the list. It is Ok,
gcc is in the list.
Authentication succeeded. The PR gains the status of commercial
technical support call and the responsible persons are notified
the fact.

If something is wrong then the authentication failed and the 
problem report is treated as ordinary PR.

In either case the submitter is notified the result.

2.1.6. "VISA" authentication

If user had supplied VISA XXXX XXXX XXXX XXXX then
the on-line charge authorization program is executed
and XXXX XXXX XXXX XXXX is transferred to it. The authorization
program checks the validity of credit card number,
makes charge operation and reports the charge operation
transaction number. Besides if the authorization is succeeded
the program returns the response time for the submitter.

A stub authorization program "auth-pr" is used as charge
authorization program. It has its own credit card database
named "cards" located where "auth-pr" does. The file is
composed of the first line containing the last transaction
number and the other lines containing the valid credit card
numbers. It checks the input XXXX XXXX XXXX XXXX for correspondence
to any but the first line of the "cards" file. If the line
XXXX XXXX XXXX XXXX is present in the "cards" file then the
authorization succeeded, last transaction number is incremented
and "auth-pr" outputs "last-transaction-number:response-time"
where last-transaction-number and response-time are numbers.
The default response time 24 business hours is used for all
credit cards.

If something is wrong then the authentication failed and the 
problem report is treated as ordinary PR.

"auth-pr" is not a part of GNATS it is a stub.

In either case the submitter notified the result.

2.2. Billing information encryption & decryption.

If any billing information was supplied then the authetication result
and the billing information is stored in "billing" file as encrypted
information.

The file may be decrypted with "decrypt" program executed in the
directory where "billing" resides.

"decrypt" may be made with
  cc -o decrypt decrypt.c

decrypt.c is in the patch tar file.

"decrypt" in not a part of GNATS.

2.3. Billing status upgrade

Submitter may convert his problem report into commercial technical
support call with "upgrade-pr" utility.

Submitter should fill in the fields in the form (like in "send-pr").
The field ">Billing-Info:" should contain submitter billing
information and the reference to the previous problem report.

...
>Billing-Info:  VISA 1234 1234 1234 1234   PR 1234
...

PR 1234 - is the reference to problem report 1234

Authentication procedure is the same as for new problem report.

If authentication had succeeded then the responsible persons are
notified the fact.

The submitter is notified the result.

2.4. Submission addition information.

Submitter may provide addition information with "upgrade-pr"
utility.

Submitter should fill in the fields in the form (like in "send-pr").
The field ">Billing-Info:" should contain the reference to the
previous problem report (PR XXXX).

The supplied information is concatenated to the corresponding
fields.

The submitter is notified the result.

2.5. Requesting patches.

Submitter may request patches for "closed" or "feedback"
problem reports with "request-patch" utility.

Submutter should fill in the form (like in "send-pr")
where he supplies problem report number, category, the
release identifer he has, his e-mail address.

2.5.1. Submission patches

For developers (maintainers):

Releases and patches should be tagged with CVS according the
following rules:

a) dots (".") in releases should changed to minuses "-";
b) release tag should be prepended with "RELEASE-";
c) patch tag should be prepended with "PATCH-".

Example:
release real name: gcc-2.7.5
release tag in cvs: RELEASE-gcc2-7-5

patch problem report: 123
patch tag: PATCH-123

2.6. Technical support rating.

Submitter may fill out technical support rating reports
where he appreciates technical support for the problem
report (commercial technical support call) he had supplied.
The utility "rating-pr" is intended for providing that
capability.

Submitter fills in the form where he rates response quality,
quickness, courtesy. Also he may provide additional information
in ">Rating-Comments:".

2.6.1. Rating summary retrival

Rating information is stored in $category/.rating file.
It has two sources of information:
  - "edit-pr";
  - rating reports of submitters.

"edit-pr" adds records to the file when the report state
is changed to "closed" in "edit-pr" utility.

Rating report information is also stored in that files.

GNATS administrator or another person in charge may
get rating reports for the specified person, the specified
category or for both with "rating-sum" utiltiy.

Here, the options for the utility:

rating-sum [-V] [-s start-date] [-e end-date] [-r responsible]
       [-c category] [-S[r|c|a]] -q
       -V show version
       -s date should be of yyyy/mm/dd format if omitted from 1970/1/1
       -e date should be of yyyy/mm/dd format if omitted until now
       -r responsible person e-mail address (regular expression accepted)
       -c category (regular expression accepted)
       -Sr summary for responsible
       -Sc summary for category
       -Sa summary for category and responsible
       -q show only summary"

3. WWW GNATS

WWW GNATS interface duplicates e-mail GNATS capabilities.
WWW GNATS is available at URL: $localhost/cgi-bin/pr.pl
where $localhost is the name of WWW GNATS site.

