/contrib/cvs/man/cvsbug.8

  1.\" -*- nroff -*-
  2.\" ---------------------------------------------------------------------------
  3.\"    man page for send-pr (by Heinz G. Seidl, hgs@cygnus.com)
  4.\"    updated Feb 1993 for GNATS 3.00 by Jeffrey Osier, jeffrey@cygnus.com
  5.\"
  6.\"    This file is part of the Problem Report Management System (GNATS)
  7.\"    Copyright 1992 Cygnus Support
  8.\"
  9.\"    This program is free software; you can redistribute it and/or
 10.\"    modify it under the terms of the GNU General Public
 11.\"    License as published by the Free Software Foundation; either
 12.\"    version 2 of the License, or (at your option) any later version.
 13.\"
 14.\"    This program is distributed in the hope that it will be useful,
 15.\"    but WITHOUT ANY WARRANTY; without even the implied warranty of
 16.\"    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 17.\"    General Public License for more details.
 18.\"
 19.\" ---------------------------------------------------------------------------
 20.\" $FreeBSD$
 21.nh
 22.TH CVSBUG 8 xVERSIONx "February 1993"
 23.SH NAME
 24cvsbug \- send problem report (PR) about CVS to a central support site
 25.SH SYNOPSIS
 26.B cvsbug
 27[
 28.I site
 29]
 30[
 31.B \-f
 32.I problem-report
 33]
 34[
 35.B \-t
 36.I mail-address
 37]
 38.br
 39.in +0.8i
 40[
 41.B \-P
 42]
 43[
 44.B \-L
 45]
 46[
 47.B \-\-request-id
 48]
 49[
 50.B \-v
 51]
 52.SH DESCRIPTION
 53.B cvsbug
 54is a tool used to submit 
 55.I problem reports 
 56.\" SITE ADMINISTRATORS - change this if you use a local default
 57(PRs) to a central support site.  In most cases the correct 
 58.I site
 59will be the default.  This argument indicates the support site which
 60is responsible for the category of problem involved.  Some sites may
 61use a local address as a default.  
 62.I site
 63values are defined by using the 
 64.BR aliases (5).
 65.LP
 66.B cvsbug
 67invokes an editor on a problem report template (after trying to fill
 68in some fields with reasonable default values).  When you exit the
 69editor,
 70.B cvsbug 
 71sends the completed form to the
 72.I Problem Report Management System
 73(\fBGNATS\fR) at a central support site.  At the support site, the PR
 74is assigned a unique number and is stored in the \fBGNATS\fR database
 75according to its category and submitter-id.  \fBGNATS\fR automatically
 76replies with an acknowledgement, citing the category and the PR
 77number.
 78.LP
 79To ensure that a PR is handled promptly, it should contain your (unique)
 80\fIsubmitter-id\fR and one of the available \fIcategories\fR to identify the
 81problem area.  (Use
 82.B `cvsbug -L'
 83to see a list of categories.)
 84.LP
 85The
 86.B cvsbug
 87template at your site should already be customized with your
 88submitter-id (running `\|\fBinstall-sid\fP \fIsubmitter-id\fP\|' to
 89accomplish this is part of the installation procedures for
 90.BR cvsbug ).
 91If this hasn't been done, see your system administrator for your
 92submitter-id, or request one from your support site by invoking
 93.B `cvsbug \-\-request\-id'.
 94If your site does not distinguish between different user sites, or if
 95you are not affiliated with the support site, use
 96.B `net'
 97for this field.
 98.LP
 99The more precise your problem description and the more complete your
100information, the faster your support team can solve your problems.
101.SH OPTIONS
102.TP
103.BI \-f " problem-report"
104specify a file (\fIproblem-report\fR) which already contains a
105complete problem report.
106.B cvsbug
107sends the contents of the file without invoking the editor.  If 
108the value for 
109.I problem-report
110is
111.BR `\|\-\|' ,
112then
113.B cvsbug
114reads from standard input.
115.TP
116.BI \-t " mail-address"
117Change mail address at the support site for problem reports.  The
118default 
119.I mail-address
120is the address used for the default 
121.IR site .  
122Use the
123.I site
124argument rather than this option in nearly all cases.
125.TP
126.B \-P
127print the form specified by the environment variable 
128.B PR_FORM 
129on standard output.  If 
130.B PR_FORM
131is not set, print the standard blank PR template.  No mail is sent.
132.TP
133.B -L
134print the list of available categories.  No mail is sent.
135.TP
136.B \-\-request\-id
137sends mail to the default support site, or
138.I site
139if specified, with a request for your 
140.IR submitter-id . 
141If you are
142not affiliated with 
143.IR site ,
144use a
145.I submitter-id
146of
147.BR net \|'.
148.TP
149.B \-v
150Display the 
151.B cvsbug
152version number.
153.LP
154Note: use
155.B cvsbug
156to submit problem reports rather than mailing them directly.  Using
157both the template and
158.B cvsbug
159itself will help ensure all necessary information will reach the
160support site.
161.SH ENVIRONMENT
162The environment variable 
163.B EDITOR
164specifies the editor to invoke on the template.
165.br
166default:
167.B vi
168.sp
169If the environment variable 
170.B PR_FORM
171is set, then its value is used as the file name of the template for
172your problem-report editing session.  You can use this to start with a
173partially completed form (for example, a form with the identification
174fields already completed).
175.SH "HOW TO FILL OUT A PROBLEM REPORT"
176Problem reports have to be in a particular form so that a program can
177easily manage them.  Please remember the following guidelines:
178.IP \(bu 3m 
179describe only 
180.B one problem
181with each problem report.
182.IP \(bu 3m
183For follow-up mail, use the same subject line as the one in the automatic
184acknowledgement. It consists of category, PR number and the original synopsis
185line.  This allows the support site to relate several mail messages to a
186particular PR and to record them automatically.
187.IP \(bu 3m 
188Please try to be as accurate as possible in the subject and/or synopsis line.
189.IP \(bu 3m 
190The subject and the synopsis line are not confidential.  This is
191because open-bugs lists are compiled from them.  Avoid confidential
192information there.
193.LP
194See the GNU 
195.B Info 
196file
197.B cvsbug.info
198or the document \fIReporting Problems With cvsbug\fR\ for detailed
199information on reporting problems
200.SH "HOW TO SUBMIT TEST CASES, CODE, ETC."
201Submit small code samples with the PR.  Contact the support site for
202instructions on submitting larger test cases and problematic source
203code.
204.SH FILES
205.ta \w'/tmp/pbad$$  'u
206/tmp/p$$	copy of PR used in editing session
207.br
208/tmp/pf$$	copy of empty PR form, for testing purposes
209.br
210/tmp/pbad$$	file for rejected PRs
211.SH INSTALLATION AND CONFIGURATION
212See 
213.B INSTALL
214for installation instructions.
215.SH SEE ALSO
216.BR gnats (l),
217.BR query-pr (1),
218.BR edit-pr (1),
219.BR gnats (8),
220.BR queue-pr (8),
221.BR at-pr (8),
222.BR mkcat (8),
223.BR mkdist (8).
224.SH AUTHORS
225Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus
226Support)
227.SH COPYING
228Copyright (c) 1992, 1993 Free Software Foundation, Inc.
229.PP
230Permission is granted to make and distribute verbatim copies of
231this manual provided the copyright notice and this permission notice
232are preserved on all copies.
233.PP
234Permission is granted to copy and distribute modified versions of this
235manual under the conditions for verbatim copying, provided that the
236entire resulting derived work is distributed under the terms of a
237permission notice identical to this one.
238.PP
239Permission is granted to copy and distribute translations of this
240manual into another language, under the above conditions for modified
241versions, except that this permission notice may be included in
242translations approved by the Free Software Foundation instead of in
243the original English.
244