| % File src/library/utils/man/bug.report.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{bug.report} |
| \alias{bug.report} |
| \title{Send a Bug Report} |
| \usage{ |
| bug.report(subject = "", address, |
| file = "R.bug.report", package = NULL, lib.loc = NULL, |
| \dots) |
| } |
| \arguments{ |
| \item{subject}{Subject of the email.} |
| \item{address}{Recipient's email address, where applicable: for |
| package bug reports sent by email this defaults to the address of |
| the package maintainer (the first if more than one is listed).} |
| \item{file}{filename to use (if needed) for setting up the email.} |
| \item{package}{Optional character vector naming a single package which is |
| the subject of the bug report.} |
| \item{lib.loc}{A character vector describing the location of \R |
| library trees in which to search for the package, or \code{NULL}. |
| The default value of \code{NULL} corresponds to all libraries |
| currently known.} |
| \item{\dots}{additional named arguments such as \code{method} and |
| \code{ccaddress} to pass to \code{\link{create.post}}.} |
| } |
| \description{ |
| Invokes an editor or email program to write a bug report or opens a |
| web page for bug submission. Some standard information on the current |
| version and configuration of \R are included automatically. |
| } |
| \details{ |
| If \code{package} is \code{NULL} or a base package, this opens the R |
| bugs tracker at \url{https://bugs.r-project.org/}. |
| |
| If \code{package} is specified, it is assumed that the bug report is |
| about that package, and parts of its \file{DESCRIPTION} file are added |
| to the standard information. If the package has a non-empty |
| \code{BugReports} field in the \file{DESCRIPTION} file specifying the |
| URL of a webpage, that URL will be opened using |
| \code{\link{browseURL}}, otherwise an email directed to the package |
| maintainer will be generated using \code{\link{create.post}}. If |
| there is any other form of \code{BugReports} field or a \code{Contact} |
| field, this is examined as it may provide a preferred email address. |
| } |
| \value{Nothing useful.} |
| \section{When is there a bug?}{ |
| If \R executes an illegal instruction, or dies with an operating |
| system error message that indicates a problem in the program (as |
| opposed to something like \dQuote{disk full}), then it is certainly a |
| bug. |
| |
| Taking forever to complete a command can be a bug, but you must make |
| certain that it was really \R's fault. Some commands simply take a |
| long time. If the input was such that you KNOW it should have been |
| processed quickly, report a bug. If you don't know whether the |
| command should take a long time, find out by looking in the manual or |
| by asking for assistance. |
| |
| If a command you are familiar with causes an \R error message in a |
| case where its usual definition ought to be reasonable, it is probably |
| a bug. If a command does the wrong thing, that is a bug. But be sure |
| you know for certain what it ought to have done. If you aren't |
| familiar with the command, or don't know for certain how the command |
| is supposed to work, then it might actually be working right. Rather |
| than jumping to conclusions, show the problem to someone who knows for |
| certain. |
| |
| Finally, a command's intended definition may not be best for |
| statistical analysis. This is a very important sort of problem, but |
| it is also a matter of judgement. Also, it is easy to come to such a |
| conclusion out of ignorance of some of the existing features. It is |
| probably best not to complain about such a problem until you have |
| checked the documentation in the usual ways, feel confident that you |
| understand it, and know for certain that what you want is not |
| available. The mailing list \code{r-devel@r-project.org} is a better |
| place for discussions of this sort than the bug list. |
| |
| If you are not sure what the command is supposed to do |
| after a careful reading of the manual this indicates a bug in the |
| manual. The manual's job is to make everything clear. It is just as |
| important to report documentation bugs as program bugs. |
| |
| If the online argument list of a function disagrees with the manual, |
| one of them must be wrong, so report the bug. |
| } |
| \section{How to report a bug}{ |
| When you decide that there is a bug, it is important to report it and |
| to report it in a way which is useful. What is most useful is an |
| exact description of what commands you type, from when you start \R |
| until the problem happens. Always include the version of \R, machine, |
| and operating system that you are using; type \kbd{version} in \R to |
| print this. To help us keep track of which bugs have been fixed and |
| which are still open please send a separate report for each bug. |
| |
| The most important principle in reporting a bug is to report FACTS, |
| not hypotheses or categorizations. It is always easier to report the |
| facts, but people seem to prefer to strain to posit explanations and |
| report them instead. If the explanations are based on guesses about |
| how \R is implemented, they will be useless; we will have to try to |
| figure out what the facts must have been to lead to such |
| speculations. Sometimes this is impossible. But in any case, it is |
| unnecessary work for us. |
| |
| For example, suppose that on a data set which you know to be quite |
| large the command \code{data.frame(x, y, z, monday, tuesday)} never |
| returns. Do not report that \code{data.frame()} fails for large data |
| sets. Perhaps it fails when a variable name is a day of the week. If |
| this is so then when we got your report we would try out the |
| \code{data.frame()} command on a large data set, probably with no day |
| of the week variable name, and not see any problem. There is no way in |
| the world that we could guess that we should try a day of the week |
| variable name. |
| |
| Or perhaps the command fails because the last command you used was a |
| \code{[} method that had a bug causing \R's internal data structures |
| to be corrupted and making the \code{data.frame()} command fail from |
| then on. This is why we need to know what other commands you have |
| typed (or read from your startup file). |
| |
| It is very useful to try and find simple examples that produce |
| apparently the same bug, and somewhat useful to find simple examples |
| that might be expected to produce the bug but actually do not. If you |
| want to debug the problem and find exactly what caused it, that is |
| wonderful. You should still report the facts as well as any |
| explanations or solutions. |
| |
| Invoking \R with the \option{--vanilla} option may help in isolating a |
| bug. This ensures that the site profile and saved data files are not |
| read. |
| |
| A bug report can be generated using the function \code{bug.report()}. |
| For reports on \R this will open the Web page at |
| \url{https://bugs.r-project.org/}: for a contributed package it will |
| open the package's bug tracker Web page or help you compose an email |
| to the maintainer. |
| |
| Bug reports on \strong{contributed packages} should not be sent to the |
| R bug tracker: rather make use of the \code{package} argument. |
| } |
| \seealso{ |
| \code{\link{help.request}} which you possibly should try |
| \emph{before} \code{bug.report}. |
| |
| \code{\link{create.post}}, which handles emailing reports. |
| |
| The R FAQ, also \code{\link{sessionInfo}()} from which you may add |
| to the bug report. |
| } |
| \author{This help page is adapted from the Emacs manual and the R FAQ} |
| \keyword{utilities} |
| \keyword{error} |