Bug Reporting in R

This document explains what to do if you find a bug in the R project,or have a patch that you’d like to submit. It covers:

1. Making sure your problem is a bug;
2. Where to submit bug reports (see spam protectionNote!)
3. How to write useful and productive bug reports;
4. How to submit patches;
5. What to do if something goes wrong.

The intent is to make the most of your time and the R developers’time, by ensuring that bug reports are clear-cut and easy for thedevelopers to respond to.

Making sure it’s a bug

There are a couple of situations where something is definitely a bug;one example of those is when the R session unexpectedly terminates, orsegfaults. This looks something like:

    *** caught segfault ***address (nil), cause 'memory not mapped'

If you’re seeing an error like this, unless you have written your owncall to compiled code or an internal function (e.g. via.Cor.Internal), it’s definitely a bug¹.

Other examples of obvious bugs are situations where code does not dowhat the documentation says it should: either the code is wrong, or thedocumentation is. One way or another something needs fixing.

Code doing somethingunexpected is not necessarily a bug -make sure to carefully review the documentation for the function you arecalling to see if the behaviour it exhibits is what it was designed todo, even if it’s not what you want. Similarly, issues withseemingly-identicalnumbers not being equal are known, documented and intractableproblems - not bugs.

In all cases, if you think it might be a bug, try launching R fromthe command line with the--vanilla option, to make sureit’s a clean session, and see if the bug still appears then. Reduce yourcode to the minimum required to run the function call where the bugoccurred, in particular, only attaching packages required by that call(if any).

If, rather than a bug, you have a suggestion for a new feature in R,you can submit this to the same place you would submit a bug, see thenext section.

If your issue doesn’t fall into any of these categories - if it’s Rrunning slower than expected, say, or something working but not beingdefined in the way you think would be best, you should consult someone.If you don’t know anyone who can look over your code and see if it canbe sped up, or if another function would suit your needs better, someuseful places to ask for help are:

1. The r-helpmailing list; orotherR mailing lists.
2. The Bioconductor supportsite.
3. The R sectionof StackOverflow.
4. The R Internet RelayChat (IRC) channel.

Where to submit bugreports and patches

If your problem is definitely a bug - either because it falls intoone of the bug categories above, or because you’ve asked people for helpand they’ve confirmed it’s an issue - it’s time to submit a report sothat it can be fixed.

Depending on the problem, you might need to submit bug reports indifferent places. The first step is to see which package the functionwith a bug comes from. The R Core team only maintains the core languageand the R packages labelled withMaintainer: R Core Team <R-core@r-project.org>. Youcan see this label by running e.g. maintainer("graphics")in R.
NOTE however: Donot send e-mail to R-core about bugsetc, not even security vulnerabilities !!

If your bug is insomePkg and that is not maintained bythe R Core team, you should submit your report to the packagemaintainer. Runningbug.report(package = "somePkg") directsyou to the right place, either opening the relevant bug tracking webpage or helping you to compose an email to the package maintainer.

Thebug.report function is disabled in some IDEs(e.g. RStudio) to avoid misuse; to identify the right place to submit areport yourself, start by looking at the output ofpackageDescription("somePkg"), the R help for the package,or the webpage for the package from the relevant repository, e.g. CRANorBioconductor.Some packages have a bug submission page, such as an issue tracker onGitHub, listed under theBugReports field in the packagedescription. If you follow this link you may find your bug has alreadybeen reported, otherwise you can submit your report there, following theguidelines on bug reporting discussed below. If there is no bugsubmission page, you should email your bug report to the packageMaintainer via the address in the package description.

If your bug is in the language, though, or the Core-supportedpackages, you should submit your report to R’sBugzilla.
NOTE: due to abuse by spammers, since 2016-07-09 only “members”(including all who have previously submitted bugs) can submit new bugson R’s Bugzilla. In order to get a bugzilla account (i.e., become“member”), please send an e-mail (from the address you want to use asyour login) tobug-report-request@r-project.org brieflyexplaining why, i.e., withsome details, and a volunteer willadd you to R’s Bugzilla members. It is important to try to makesure that the report isn’t extraneous. The easiest way to do this is tofirst look at theupcoming changes inR, to see if the bug has already been patched (just not releasedyet), and tobrowsethe latest bug reports orsearch for the bug inBugzilla to see if (even if it hasn’t been patched yet) it has beenreported. If your bug has not yet been reported or fixed, you can reportthe bug following the guidelines in the sectionWriting a good bug report. If youhave a patch accompanying your bug, see the sectionHow to submit patches.

By default, reports submitted to R’sBugzilla are public. If youbelieve your bug is a security vulnerability and should not be public,you may select “Show advanced fields” on the bug submission page, scrolldown to the bottom of the page, and check that only members ofR-security group are allowed to see the bug. Before checking this flag,it is good to try to make sure the vulnerability is really securitysensitive, that exploiting it would allow an attacker to execute codethat could not be executed using the standard R functionality from thesame context. Notesystem(),system2(),dyn.load() can be used by design to execute arbitrarycode.

If you wish to submit a feature request, rather than a bug report,your best bet is to ask about it first on ther-devel mailinglist. If the feedback is positive, you can submit your suggestion usingthe bug reporting form on Bugzilla, where you should selectWishlist in theComponent field and start yoursummary withWishlist:.

Issues related to message translations should be sent to the lasttranslator or to the relevanttranslationteam. To find the last translator, you will need to look at thecomments at the top of the relevant.po file in the Rsource code, for example German translations of messages in the basepackage are insrc/library/base/po/R-de.po. You candownload the R source code from CRAN, or otherwisebrowse the R-devel sourcesortheir mirror onGitHub.

Writing a good bug report

Bug reports should include a way ofreproducing thebug. This should be as simple as possible. If the person trying to fixthe bug can’t work out how to make it appear, or has to jump through alot of unnecessary hoops to make it appear, you’re going to waste a lotof their time.

Bugzilla is maintained by a small number of people, so it’s best tomake sure your bug report is clear and well-written. If it’s not, itwill suck in more energy from the maintainers and take longer for thebug to get fixed - or it may end up not getting handled at all. Inparticular, you should:

1. Write a clear and unique summary for the bug. “Stopping a run oflm() causes a crash” is good; “software crashes” is not.
2. Include, in the description, the steps to reproduce the bugmentioned above.
3. Identify both what happened (“the software crashed”) and what youexpected to happen (“lm() should stop running”).
4. Identify the platform, architecture, and version of R where youfound this bug. You can retrieve that from within R by typingR.version.
5. Just focus on the facts of what happened, rather than on yourtheories of what the bug is and where it comes from.

At that point, you’ve written a good bug report! Sit back and waitfor a developer to respond to it. If you run into any problems with thatresponse, see the sectionWhat to do if there’s anissue.

How to submit patches

Sometimes you’ll find a bug and also see, from looking at the code,how to fix it. When this happens you’ve got the opportunity to submit apatch, which can reduce the workload on the R developers: they get totest, tweak and include the code instead of having to write it all fromscratch.

To prepare a patch, you’re going to need the latest developer versionof R. This is maintained in aSubversion (SVN) repository.Once you’ve got SVN installed on your system, open the command line andtype:

svn checkout https://svn.r-project.org/R/trunk/ R-devel

This should create a directory,R-devel, in your currentworking directory. This contains the source code for the newest versionof R.

Go through and make the changes you need to make in order to patchthe bug - try to keep to whatever coding style and conventions thefunctions you’re changing use, just to make things easier. Once you’redone, go to theR-devel directory in your terminal andtype:

svn updatesvn diff > patch.diff

This updates the code then creates a new file,patch.diff, that contains the changes between the latestversion of R, and your alterations. And that’s a patch! Beforesubmitting the patch, make sure that the built system works correctly byrunning:

make check-devel

Read the output and look for notes, warnings, and errors. Finally,attach the patch to the bug report you’re writing, note in the reportthat there’s an associated patch, and you’re done.

What to do if there is anissue

In an ideal world you write an informative bug report (and maybesubmit a patch), someone comes along promptly and fixes it, and everyoneis happy. In the world we’ve got, the people maintaining R have a lot ofresponsibilities, and all of them are doing this work as volunteers.This means that, practically speaking, bugs may take a very long time toget fixed, accidentally get missed, or result in an unexpected orunpleasant outcome - not out of any maliciousness but simply because thepeople responsible for the software can get pretty stressed.

If you experience technical issues with R’s Bugzilla that do notresolve themselves after a period of time, you should contact thecurrent maintainer:simon.urbanek@R-project.org.If you feel like your bug has been missed (e.g. because a new release ofR has come out, and it was not fixed), you can bring attention to it bysimply adding a comment like “This is still present in the x.y.zrelease” on Bugzilla. Even better would be to install a pre-releasealpha or beta version to confirm it is still present, and reportthat.

If you feel it has been assessed wrongly, you can leave a comment tothat effect on Bugzilla. If you are personally acquainted with a memberof R Core you could contact them directly. In either case, present yourcase clearly, and respect the fact that the R Core members may judge theimportance of the issue (or even whether it is a bug or not) differentlythan you do.