| Line 1... |
Line 1... |
| 1 |
% File src/library/utils/man/bug.report.Rd
|
1 |
% File src/library/utils/man/bug.report.Rd
|
| 2 |
% Part of the R package, https://www.R-project.org
|
2 |
% Part of the R package, https://www.R-project.org
|
| 3 |
% Copyright 1995-2017 R Core Team
|
3 |
% Copyright 1995-2025 R Core Team
|
| 4 |
% Distributed under GPL 2 or later
|
4 |
% Distributed under GPL 2 or later
|
| 5 |
|
5 |
|
| 6 |
\name{bug.report}
|
6 |
\name{bug.report}
|
| 7 |
\alias{bug.report}
|
7 |
\alias{bug.report}
|
| 8 |
\title{Send a Bug Report}
|
8 |
\title{Send a Bug Report}
|
| 9 |
\usage{
|
9 |
\usage{
|
| 10 |
bug.report(subject = "", address,
|
10 |
bug.report(subject = "", address, file = "R.bug.report",
|
| 11 |
file = "R.bug.report", package = NULL, lib.loc = NULL,
|
11 |
package = NULL, lib.loc = NULL, \dots)
|
| 12 |
\dots)
|
- |
|
| 13 |
}
|
12 |
}
|
| 14 |
\arguments{
|
13 |
\arguments{
|
| 15 |
\item{subject}{Subject of the email.}
|
14 |
\item{subject}{the subject of the email (if one is composed).}
|
| 16 |
\item{address}{Recipient's email address, where applicable: for
|
15 |
\item{address}{the recipient's email address, which is by default
|
| 17 |
package bug reports sent by email this defaults to the address of
|
16 |
inferred from the \code{\link{packageDescription}}
|
| 18 |
the package maintainer (the first if more than one is listed).}
|
17 |
(see \sQuote{Details}).}
|
| 19 |
\item{file}{filename to use (if needed) for setting up the email.}
|
18 |
\item{file}{filename to use (if needed) for setting up the email.}
|
| 20 |
\item{package}{Optional character vector naming a single package which is
|
19 |
\item{package}{an optional character string naming a single package which is
|
| 21 |
the subject of the bug report.}
|
20 |
the subject of the bug report.}
|
| 22 |
\item{lib.loc}{A character vector describing the location of \R
|
21 |
\item{lib.loc}{a character vector describing the location of \R
|
| 23 |
library trees in which to search for the package, or \code{NULL}.
|
22 |
library trees in which to search for the package, or \code{NULL}.
|
| 24 |
The default value of \code{NULL} corresponds to all libraries
|
23 |
The default value of \code{NULL} corresponds to all libraries
|
| 25 |
currently known.}
|
24 |
currently known.}
|
| 26 |
\item{\dots}{additional named arguments such as \code{method} and
|
25 |
\item{\dots}{additional named arguments such as \code{method} and
|
| 27 |
\code{ccaddress} to pass to \code{\link{create.post}}.}
|
26 |
\code{ccaddress} to pass to \code{\link{create.post}}.}
|
| 28 |
}
|
27 |
}
|
| 29 |
\description{
|
28 |
\description{
|
| 30 |
Invokes an editor or email program to write a bug report or opens a
|
29 |
Invokes an editor or email program to write a bug report or opens a
|
| 31 |
web page for bug submission. Some standard information on the current
|
30 |
web page for bug submission. Some standard information on the current
|
| 32 |
version and configuration of \R are included automatically.
|
31 |
version and configuration of \R are generated automatically.
|
| 33 |
}
|
32 |
}
|
| 34 |
\details{
|
33 |
\details{
|
| 35 |
If \code{package} is \code{NULL} or a base package, this opens the R
|
34 |
If \code{package} is \code{NULL} or a base package, this opens the \R
|
| 36 |
bugs tracker at \url{https://bugs.r-project.org/}.
|
35 |
bug tracker at \url{https://bugs.R-project.org/}.
|
| 37 |
|
36 |
|
| 38 |
If \code{package} is specified, it is assumed that the bug report is
|
37 |
If \code{package} is specified, it is assumed that the bug report is
|
| 39 |
about that package, and parts of its \file{DESCRIPTION} file are added
|
38 |
about that package, and parts of its \file{DESCRIPTION} file are added
|
| 40 |
to the standard information. If the package has a non-empty
|
39 |
to the standard information. If the package has a non-empty
|
| 41 |
\code{BugReports} field in the \file{DESCRIPTION} file specifying the
|
40 |
\code{BugReports} field in the \file{DESCRIPTION} file specifying the
|
| Line 44... |
Line 43... |
| 44 |
maintainer will be generated using \code{\link{create.post}}. If
|
43 |
maintainer will be generated using \code{\link{create.post}}. If
|
| 45 |
there is any other form of \code{BugReports} field or a \code{Contact}
|
44 |
there is any other form of \code{BugReports} field or a \code{Contact}
|
| 46 |
field, this is examined as it may provide a preferred email address.
|
45 |
field, this is examined as it may provide a preferred email address.
|
| 47 |
}
|
46 |
}
|
| 48 |
\value{Nothing useful.}
|
47 |
\value{Nothing useful.}
|
| 49 |
\section{When is there a bug?}{
|
- |
|
| 50 |
If \R executes an illegal instruction, or dies with an operating
|
- |
|
| 51 |
system error message that indicates a problem in the program (as
|
- |
|
| 52 |
opposed to something like \dQuote{disk full}), then it is certainly a
|
- |
|
| 53 |
bug.
|
- |
|
| 54 |
|
- |
|
| 55 |
Taking forever to complete a command can be a bug, but you must make
|
- |
|
| 56 |
certain that it was really \R's fault. Some commands simply take a
|
- |
|
| 57 |
long time. If the input was such that you KNOW it should have been
|
- |
|
| 58 |
processed quickly, report a bug. If you don't know whether the
|
- |
|
| 59 |
command should take a long time, find out by looking in the manual or
|
- |
|
| 60 |
by asking for assistance.
|
- |
|
| 61 |
|
- |
|
| 62 |
If a command you are familiar with causes an \R error message in a
|
- |
|
| 63 |
case where its usual definition ought to be reasonable, it is probably
|
- |
|
| 64 |
a bug. If a command does the wrong thing, that is a bug. But be sure
|
- |
|
| 65 |
you know for certain what it ought to have done. If you aren't
|
- |
|
| 66 |
familiar with the command, or don't know for certain how the command
|
- |
|
| 67 |
is supposed to work, then it might actually be working right. Rather
|
- |
|
| 68 |
than jumping to conclusions, show the problem to someone who knows for
|
- |
|
| 69 |
certain.
|
- |
|
| 70 |
|
- |
|
| 71 |
Finally, a command's intended definition may not be best for
|
- |
|
| 72 |
statistical analysis. This is a very important sort of problem, but
|
- |
|
| 73 |
it is also a matter of judgement. Also, it is easy to come to such a
|
- |
|
| 74 |
conclusion out of ignorance of some of the existing features. It is
|
- |
|
| 75 |
probably best not to complain about such a problem until you have
|
- |
|
| 76 |
checked the documentation in the usual ways, feel confident that you
|
- |
|
| 77 |
understand it, and know for certain that what you want is not
|
- |
|
| 78 |
available. The mailing list \code{r-devel@r-project.org} is a better
|
- |
|
| 79 |
place for discussions of this sort than the bug list.
|
- |
|
| 80 |
|
- |
|
| 81 |
If you are not sure what the command is supposed to do
|
- |
|
| 82 |
after a careful reading of the manual this indicates a bug in the
|
- |
|
| 83 |
manual. The manual's job is to make everything clear. It is just as
|
- |
|
| 84 |
important to report documentation bugs as program bugs.
|
- |
|
| 85 |
|
- |
|
| 86 |
If the online argument list of a function disagrees with the manual,
|
- |
|
| 87 |
one of them must be wrong, so report the bug.
|
- |
|
| 88 |
}
|
- |
|
| 89 |
\section{How to report a bug}{
|
- |
|
| 90 |
When you decide that there is a bug, it is important to report it and
|
- |
|
| 91 |
to report it in a way which is useful. What is most useful is an
|
- |
|
| 92 |
exact description of what commands you type, from when you start \R
|
- |
|
| 93 |
until the problem happens. Always include the version of \R, machine,
|
- |
|
| 94 |
and operating system that you are using; type \kbd{version} in \R to
|
- |
|
| 95 |
print this. To help us keep track of which bugs have been fixed and
|
- |
|
| 96 |
which are still open please send a separate report for each bug.
|
- |
|
| 97 |
|
- |
|
| 98 |
The most important principle in reporting a bug is to report FACTS,
|
- |
|
| 99 |
not hypotheses or categorizations. It is always easier to report the
|
- |
|
| 100 |
facts, but people seem to prefer to strain to posit explanations and
|
- |
|
| 101 |
report them instead. If the explanations are based on guesses about
|
- |
|
| 102 |
how \R is implemented, they will be useless; we will have to try to
|
- |
|
| 103 |
figure out what the facts must have been to lead to such
|
- |
|
| 104 |
speculations. Sometimes this is impossible. But in any case, it is
|
- |
|
| 105 |
unnecessary work for us.
|
- |
|
| 106 |
|
- |
|
| 107 |
For example, suppose that on a data set which you know to be quite
|
- |
|
| 108 |
large the command \code{data.frame(x, y, z, monday, tuesday)} never
|
- |
|
| 109 |
returns. Do not report that \code{data.frame()} fails for large data
|
- |
|
| 110 |
sets. Perhaps it fails when a variable name is a day of the week. If
|
- |
|
| 111 |
this is so then when we got your report we would try out the
|
- |
|
| 112 |
\code{data.frame()} command on a large data set, probably with no day
|
- |
|
| 113 |
of the week variable name, and not see any problem. There is no way in
|
- |
|
| 114 |
the world that we could guess that we should try a day of the week
|
- |
|
| 115 |
variable name.
|
- |
|
| 116 |
|
- |
|
| 117 |
Or perhaps the command fails because the last command you used was a
|
- |
|
| 118 |
\code{[} method that had a bug causing \R's internal data structures
|
- |
|
| 119 |
to be corrupted and making the \code{data.frame()} command fail from
|
- |
|
| 120 |
then on. This is why we need to know what other commands you have
|
- |
|
| 121 |
typed (or read from your startup file).
|
- |
|
| 122 |
|
- |
|
| 123 |
It is very useful to try and find simple examples that produce
|
- |
|
| 124 |
apparently the same bug, and somewhat useful to find simple examples
|
- |
|
| 125 |
that might be expected to produce the bug but actually do not. If you
|
- |
|
| 126 |
want to debug the problem and find exactly what caused it, that is
|
- |
|
| 127 |
wonderful. You should still report the facts as well as any
|
- |
|
| 128 |
explanations or solutions.
|
- |
|
| 129 |
|
- |
|
| 130 |
Invoking \R with the \option{--vanilla} option may help in isolating a
|
- |
|
| 131 |
bug. This ensures that the site profile and saved data files are not
|
- |
|
| 132 |
read.
|
- |
|
| 133 |
|
- |
|
| 134 |
A bug report can be generated using the function \code{bug.report()}.
|
- |
|
| 135 |
For reports on \R this will open the Web page at
|
- |
|
| 136 |
\url{https://bugs.r-project.org/}: for a contributed package it will
|
- |
|
| 137 |
open the package's bug tracker Web page or help you compose an email
|
- |
|
| 138 |
to the maintainer.
|
- |
|
| 139 |
|
- |
|
| 140 |
Bug reports on \strong{contributed packages} should not be sent to the
|
- |
|
| 141 |
R bug tracker: rather make use of the \code{package} argument.
|
- |
|
| 142 |
}
|
- |
|
| 143 |
\seealso{
|
48 |
\seealso{
|
| 144 |
\code{\link{help.request}} which you possibly should try
|
49 |
\code{\link{help.request}} which you possibly should try
|
| 145 |
\emph{before} \code{bug.report}.
|
50 |
\emph{before} \code{bug.report}.
|
| 146 |
|
51 |
|
| 147 |
\code{\link{create.post}}, which handles emailing reports.
|
52 |
\code{\link{create.post}}, which handles emailing reports.
|
| 148 |
|
53 |
|
| 149 |
The R FAQ, also \code{\link{sessionInfo}()} from which you may add
|
54 |
\code{\link{sessionInfo}()} from which you may add to the bug report.
|
| - |
|
55 |
|
| - |
|
56 |
Chapter \manual{R-FAQ}{R Bugs} for more information on when and how to
|
| 150 |
to the bug report.
|
57 |
report a bug in \R.
|
| 151 |
}
|
58 |
}
|
| 152 |
\author{This help page is adapted from the Emacs manual and the R FAQ}
|
- |
|
| 153 |
\keyword{utilities}
|
59 |
\keyword{utilities}
|
| 154 |
\keyword{error}
|
60 |
\keyword{error}
|
The R Project SVN
R