|
@c This is the usage section for send-pr. It is called as |
|
|
@c chapter (Invoking send-pr) by send-pr.texi, and also as |
|
|
@c section (Submitting Problem Reports) by gnats.texi (chapter/section |
|
|
@c identifiers are adjusted accordingly) |
|
|
|
|
|
@c FIXME! This still seems jumbled... |
|
|
|
|
1 |
You can invoke @code{send-pr} from a shell prompt, or from within |
You can invoke @code{send-pr} from a shell prompt, or from within |
2 |
@sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs |
@sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs |
3 |
submitting,,Submitting Problem Reports from Emacs}.) |
submitting,,Submitting Problem Reports from Emacs}.) |
46 |
|
|
47 |
@item -d @var{database}, --database @var{database} |
@item -d @var{database}, --database @var{database} |
48 |
Specifies the database to which the PR is to be submitted; if no |
Specifies the database to which the PR is to be submitted; if no |
49 |
database is specified, the local database named @samp{default} is |
database is specified, the local database named @code{default} is |
50 |
assumed. This option overrides the database specified in the |
assumed. This option overrides the database specified in the |
51 |
@code{GNATSDB} environment variable. @var{database} can also be set |
@code{GNATSDB} environment variable. @var{database} can also be set |
52 |
to a remote database by using the format for @code{GNATSDB} described |
to a remote database by using the format for @code{GNATSDB} described |
107 |
interface to @sc{gnats}}. |
interface to @sc{gnats}}. |
108 |
|
|
109 |
@node using send-pr |
@node using send-pr |
110 |
@section Creating new Problem Reports |
@section The Problem Report template |
111 |
|
|
|
@c FIXME - this is a long node |
|
112 |
Invoking @code{send-pr} presents a PR @dfn{template} with a number of |
Invoking @code{send-pr} presents a PR @dfn{template} with a number of |
113 |
fields already filled in with default values for the database you are |
fields already filled in with default values for the database you are |
114 |
submitting to. Complete the template as thoroughly as possible to |
submitting to. Complete the template as thoroughly as possible to |
115 |
make a useful bug report. Submit only one bug with each PR. |
make a useful bug report. Submit only one bug with each PR. |
116 |
|
|
117 |
@cindex template |
@cindex{template} |
118 |
A template consists of three sections: |
A template consists of three sections: |
119 |
|
|
120 |
@table @dfn |
@itemize @bullet |
121 |
@item Comments |
@item Comments |
|
The top several lines of a blank template consist of a series of |
|
|
comments that provide some basic instructions for completing the Problem |
|
|
Report, as well as a list of valid entries for the @samp{Category:} |
|
|
field. These comments are all preceded by the string @samp{SEND-PR:} |
|
|
and are erased automatically when the PR is submitted. The |
|
|
instructional comments within @samp{<} and @samp{>} are also removed. |
|
|
(Only these comments are removed; lines you provide that happen to have |
|
|
those characters in them, such as examples of shell-level redirection, |
|
|
are not affected.) |
|
|
|
|
122 |
@item Mail Header |
@item Mail Header |
|
@code{send-pr} creates a standard mail header. @code{send-pr} can be |
|
|
set up to submit PRs by e-mail or by speaking directly to the |
|
|
@sc{gnats} server, but since this header is part of the standard |
|
|
format of Problem Reports, @code{send-pr} includes it even when it is |
|
|
set up to speak directly to the server. |
|
|
|
|
|
@code{send-pr} completes all the mail header fields except the |
|
|
@samp{Subject} line with default values. (@xref{Fields,,Problem |
|
|
Report format}.) |
|
|
|
|
123 |
@item @sc{gnats} fields |
@item @sc{gnats} fields |
124 |
These are the fields that form the bulk of a @sc{gnats} Problem |
@end itemize |
|
Report. They should be filled out as completely as possible. |
|
|
(@xref{Fields,,Problem Report format}. Also see @ref{Helpful |
|
|
hints,,Helpful hints}.) |
|
|
@end table |
|
|
|
|
|
@ifset SENDPR |
|
|
@noindent |
|
|
For examples of a Problem Report template and complete Problem Report, |
|
|
see @ref{An Example}. |
|
|
@end ifset |
|
|
|
|
|
The default template contains your preconfigured @samp{Submitter-Id} |
|
|
(@pxref{send-pr.conf file,,The send-pr.conf configuration file}.) |
|
|
@code{send-pr} attempts to determine values for the @samp{Originator} |
|
|
and @samp{Organization} fields (@pxref{Fields,,Problem Report |
|
|
format}). @code{send-pr} will set the @samp{Originator} field to the |
|
|
value of the @code{NAME} environment variable if it has been set; |
|
|
similarly, @samp{Organization} will be set to the value of |
|
|
@code{ORGANIZATION}. If these variables aren't set in you |
|
|
environment, @code{send-pr} uses the values set in the local |
|
|
@file{send-pr.conf} configuration file, if that exists. If not, these |
|
|
values are left blank in the template. @code{send-pr} also attempts |
|
|
to find out some information about your system and architecture, and |
|
|
places this information in the @samp{Environment} field if it finds |
|
|
any. |
|
125 |
|
|
126 |
@code{send-pr} also provides the mail header section of the template |
The @strong{Comments section} at the top of the template contains basic |
127 |
with default values in the @samp{To}, @samp{From}, and @samp{Reply-To} |
instructions for completing the Problem Report, as well as a list of |
128 |
fields. The @samp{Subject} field is empty. |
valid entries for the @code{Category} field. One (and only one) of |
129 |
|
these values should be placed in the @code{Category} field further down |
130 |
|
in the Problem Report. |
|
@c Version 4 OK up till here. |
|
|
|
|
|
The template begins with a comment section: |
|
131 |
|
|
132 |
@cindex template comment section |
@cindex template comment section |
133 |
@cindex comment section in the PR template |
@cindex comment section in the PR template |
146 |
@end group |
@end group |
147 |
@end smallexample |
@end smallexample |
148 |
|
|
|
@noindent |
|
|
and also contains a list of valid @code{>Category:} values for the |
|
|
Support Site to whom you are submitting this Problem Report. One (and |
|
|
only one) of these values should be placed in the @code{>Category:} |
|
|
field. |
|
149 |
@ifset SENDPR |
@ifset SENDPR |
150 |
A complete sample bug report, from template to completed PR, is shown in |
A complete sample bug report, from template to completed PR, is shown in |
151 |
@ref{An Example}. For a complete list of valid categories, type |
@ref{An Example}. For a complete list of valid categories, type |
153 |
Categories}, for a sample list of categories, . |
Categories}, for a sample list of categories, . |
154 |
@end ifset |
@end ifset |
155 |
|
|
156 |
@c FIXME.. this sounds awkward |
The comments lines are all preceded by the string @samp{SEND-PR:} and |
157 |
The mail header is just below the comment section. Fill out the |
are erased automatically when the PR is submitted. The instructional |
158 |
@samp{Subject:} field, if it is not already completed using the value of |
comments within @samp{<} and @samp{>} are also removed. (Only these |
159 |
@samp{>Synopsis:}. The other mail header fields contain default values. |
comments are removed; lines you provide that happen to have those |
160 |
|
characters in them, such as examples of shell-level redirection, are not |
161 |
|
affected.) |
162 |
|
|
163 |
|
The @strong{Mail Header} section of the template contains a standard |
164 |
|
mail header constructed by @code{send-pr}. @code{send-pr} can be set up |
165 |
|
to submit PRs by e-mail or by speaking directly to the @sc{gnats} |
166 |
|
server, but since this header is part of the standard format of Problem |
167 |
|
Reports, @code{send-pr} includes it even when it is set up to speak |
168 |
|
directly to the server. |
169 |
|
|
170 |
@cindex mail header section |
@cindex mail header section |
171 |
@smallexample |
@smallexample |
172 |
@group |
@group |
173 |
To: @var{support-site} |
To: @var{PR submission address} |
174 |
Subject: @emph{complete this field} |
Subject: @emph{complete this field} |
175 |
From: @var{your-login}@@@var{your-site} |
From: @var{your-login}@@@var{your-site} |
176 |
Reply-To: @var{your-login}@@@var{your-site} |
Reply-To: @var{your-login}@@@var{your-site} |
179 |
@end smallexample |
@end smallexample |
180 |
|
|
181 |
@noindent |
@noindent |
182 |
where @var{support-site} is an alias on your local machine for the |
@code{send-pr} automatically completes all the mail header fields except |
183 |
Support Site you wish to submit this PR to. |
the @code{Subject} line with default values. (@xref{Fields,,Problem |
184 |
|
Report format}.) |
185 |
|
|
186 |
|
The @strong{@sc{gnats} fields} below the mail header form the bulk of a |
187 |
|
@sc{gnats} Problem Report. |
188 |
|
|
189 |
The rest of the template contains @sc{gnats} fields. Each field is |
Each field is either automatically completed with valid information |
190 |
either automatically completed with valid information (such as your |
(such as your @code{Submitter-Id}) or contains a one-line instruction |
191 |
@samp{>Submitter-Id:}) or contains a one-line instruction specifying the |
specifying the information that field requires in order to be correct. |
192 |
information that field requires in order to be correct. For example, |
For example, the @code{Confidential} field expects a value of @samp{yes} |
193 |
the @samp{>Confidential:} field expects a value of @samp{yes} or |
or @samp{no}, and the answer must fit on one line; similarly, the |
194 |
@samp{no}, and the answer must fit on one line; similarly, the |
@code{Synopsis} field expects a short synopsis of the problem, which |
|
@samp{>Synopsis:} field expects a short synopsis of the problem, which |
|
195 |
must also fit on one line. Fill out the fields as completely as |
must also fit on one line. Fill out the fields as completely as |
196 |
possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to |
possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to |
197 |
what kinds of information to include. |
what kinds of information to include. |
198 |
|
|
199 |
|
The mechanisms @code{send-pr} uses to fill in default values is as |
200 |
|
follows: Your preconfigured @code{Submitter-Id} is taken from the local |
201 |
|
@file{send-pr.conf} configuration file. {send-pr} will set the |
202 |
|
@code{Originator} field to the value of the @code{NAME} environment |
203 |
|
variable if it has been set; similarly, @code{Organization} will be set |
204 |
|
to the value of @code{ORGANIZATION}. If these variables aren't set in |
205 |
|
you environment, @code{send-pr} uses the values set in the local |
206 |
|
@file{send-pr.conf} configuration file, if that exists. If not, these |
207 |
|
values are left blank in the template. @code{send-pr} also attempts to |
208 |
|
find out some information about your system and architecture, and places |
209 |
|
this information in the @code{Environment} field if it finds any. |
210 |
|
|
211 |
In this example, words in @emph{italics} are filled in with |
In this example, words in @emph{italics} are filled in with |
212 |
pre-configured information: |
pre-configured information: |
213 |
|
|
214 |
@cindex @code{send-pr} fields |
@cindex @code{send-pr} fields |
215 |
@smallexample |
@smallexample |
|
@group |
|
216 |
>Submitter-Id: @emph{your submitter-id} |
>Submitter-Id: @emph{your submitter-id} |
217 |
>Originator: @emph{your name here} |
>Originator: @emph{your name here} |
218 |
>Organization: |
>Organization: |
234 |
>Fix: |
>Fix: |
235 |
<how to correct or work around the problem, if known |
<how to correct or work around the problem, if known |
236 |
(multiple lines)> |
(multiple lines)> |
|
@end group |
|
237 |
@end smallexample |
@end smallexample |
238 |
|
|
239 |
@cindex @code{Submitter-Id} field |
@cindex @code{Submitter-Id} field |
240 |
@cindex @code{>Submitter-Id} |
@cindex @code{>Submitter-Id} |
241 |
When you finish editing the Problem Report, @code{send-pr} mails it to |
When you finish editing the Problem Report, @code{send-pr} validates the |
242 |
the address named in the @samp{To:} field in the mail header. |
contents and if it looks OK either submits it directly to the |
243 |
@code{send-pr} checks that the complete form contains a valid |
@sc{gnats} server or submits it by mail to the address named in the |
244 |
@samp{>Category:}. |
@code{To} field in the mail header. |
|
|
|
|
@ifset SENDPR |
|
|
Your copy of @code{send-pr} should have already been customized on |
|
|
installation to reflect your @samp{>Submitter-Id:}. (@xref{Installing |
|
|
send-pr, , Installing @code{send-pr} on your system}.) If you don't |
|
|
know your @samp{>Submitter-Id:}, you can request it using |
|
|
@w{@samp{send-pr --request-id}}. If your organization is not affiliated |
|
|
with the site you send Problem Reports to, a good generic |
|
|
@samp{>Submitter-Id:} to use is @samp{net}. |
|
|
@end ifset |
|
245 |
|
|
246 |
@cindex bad Problem Reports |
@cindex bad Problem Reports |
247 |
@cindex errors |
@cindex errors |
248 |
@cindex invalid Problem Reports |
@cindex invalid Problem Reports |
249 |
If your PR has an invalid value in one of the @sc{Enumerated} fields |
If your PR contains one or more invalid field values, {send-pr} places |
250 |
(@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in |
the PR in a temporary file named @file{/tmp/pbad@var{nnnn}} on your |
251 |
a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine. |
machine. @var{nnnn} is the process identification number given to your |
252 |
@var{nnnn} is the process identification number given to your current |
current @code{send-pr} session. If you are running @code{send-pr} from |
253 |
@code{send-pr} session. If you are running @code{send-pr} from the |
the shell, you are prompted as to whether or not you wish to try editing |
254 |
shell, you are prompted as to whether or not you wish to try editing the |
the same Problem Report again. If you are running @code{send-pr} from |
|
same Problem Report again. If you are running @code{send-pr} from |
|
255 |
Emacs, the Problem Report is placed in the buffer |
Emacs, the Problem Report is placed in the buffer |
256 |
@w{@samp{*gnats-send*}}; you can edit this file and then submit it |
@w{@samp{*gnats-send*}}; you can edit this file and then submit it with |
257 |
with @kbd{C-c C-c}. |
@kbd{C-c C-c}. |
258 |
|
|
259 |
@cindex subsequent mail |
@cindex subsequent mail |
260 |
@cindex other mail |
@cindex other mail |
263 |
@cindex related mail |
@cindex related mail |
264 |
Any further mail concerning this Problem Report should be carbon-copied |
Any further mail concerning this Problem Report should be carbon-copied |
265 |
to the @sc{gnats} mailing address as well, with the category and |
to the @sc{gnats} mailing address as well, with the category and |
266 |
identification number in the @samp{Subject:} line of the message. |
identification number in the @code{Subject} line of the message. |
267 |
|
|
268 |
@smallexample |
@smallexample |
269 |
Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject} |
Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject} |
270 |
@end smallexample |
@end smallexample |
271 |
|
|
272 |
@noindent |
@noindent |
273 |
Messages which arrive with @samp{Subject:} lines of this form are |
Messages which arrive with @code{Subject} lines of this form are |
274 |
automatically appended to the Problem Report in the @samp{>Audit-Trail:} |
automatically appended to the Problem Report in the @code{Audit-Trail} |
275 |
field in the order received. |
field in the order they are received. |
276 |
|
|
277 |
@c ------------------------------------------------------------------------- |
@c ------------------------------------------------------------------------- |
278 |
@node Submitting via e-mail |
@node Submitting via e-mail |
279 |
@section Submitting a Problem Report via direct e-mail |
@section Submitting a Problem Report via direct e-mail |
280 |
@cindex Direct e-mail |
@cindex Direct e-mail |
281 |
@cindex Submitting a PR via e-mail |
@cindex Submitting a PR via e-mail |
282 |
In addition to using @code{send-pr}, there is another way to submit a problem |
In addition to using @code{send-pr}, there is another way to submit a |
283 |
report. You can simply send an e-mail message to the support site. |
problem report. You can simply send an e-mail message to the PR |
284 |
|
submission e-mail address of the support site (This address should be |
285 |
|
published by the support site.) |
286 |
|
|
287 |
To do this, look at the address in the @samp{To:} field of the @code{send-pr} |
When you send unformatted e-mail to this address, @sc{gnats} processes |
288 |
template. When you send unformatted e-mail to this address, @sc{gnats} |
the message as a new problem report, filling in as many fields from |
|
processes the message as a new problem report, filling in as many fields from |
|
289 |
defaults as it can: |
defaults as it can: |
290 |
|
|
291 |
@table @code |
@table @code |
292 |
@item Synopsis |
@item Synopsis |
293 |
The @samp{>Synopsis} field is filled in by the @samp{Subject:} header. |
The @code{Synopsis} field is filled in by the @code{Subject} header of |
294 |
|
the e-mail message. |
295 |
|
|
296 |
@item Submitter ID |
@item Submitter ID |
297 |
@sc{gnats} will try to derive the @samp{>Submitter} field from the address |
@sc{gnats} will try to derive the @code{Submitter} field from the address |
298 |
in the @samp{From:} header. |
in the @code{From} header of the e-mail. |
299 |
|
|
300 |
@item Description |
@item Description |
301 |
All of the text in the body of the e-mail message is put into the |
All of the text in the body of the e-mail message is put into the |
302 |
@samp{>Description} field. Each line of the text is indented by one space, |
@code{Description} field. |
|
indicating that it is "quoted text" from the sender. |
|
303 |
@end table |
@end table |
304 |
|
|
305 |
Other fields, such as category, version, severity, etc. are set to default |
Other fields, such as @code{Category}, @code{Version}, @code{Severity}, |
306 |
values (if the @sc{gnats} administrator has set them). |
etc. are set to default values as defined by the @sc{gnats} administrator. |
307 |
|
|
308 |
@c -------------------------------------------------------------------------- |
@c -------------------------------------------------------------------------- |
309 |
@node Helpful hints |
@node Helpful hints |