forked from r-devel/rdevguide
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #17 from forwards/master
rebase core-developers branch with forwards/rdevguide master branch
- Loading branch information
Showing
3 changed files
with
174 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,125 @@ | ||
| # Bug Tracking | ||
|
|
||
| ## What is a bug in R? | ||
|
|
||
| You may find a bug in R if: | ||
|
|
||
| 1. The R session terminates unexpectedly, or there is a segmentation fault, it might be a bug in R, unless you have written your own call to compiled code or an internal function (via `.C` or `.Internal`). The error may look like this: | ||
|
|
||
| ```{r, results='hide'} | ||
| ## *** caught segfault *** | ||
| ## address (nil), cause 'memory not mapped' | ||
| ``` | ||
|
|
||
| 2. If the code does not do what the documentation says it should, then either the code or the documentation is wrong. Report either of which needs to be fixed. | ||
|
|
||
| **Note**: | ||
| When you are in doubt that there is a bug: (which should be most of the time!) | ||
|
|
||
| 1. Make sure whether the bug appears in a clean session of R. Many times, there are variables/commands/functions stored in history which might cause issues. Hence, check if the issue happens in a clean session. To do so, launch R from the command line with the `--vanilla` option. | ||
|
|
||
| 2. At times the code that is written is very complicated, has numerous package and file dependencies, has many function calls, etc.. In such scenarios it is quite common that the code throws an error and you are not able to solve it. You may tend to think that there is a bug that needs to be reported. Before doing so, try to produce a minimum working example of the code for the section where the error occurred. Add only those package and files which are required by that section, and see if the error appears still. Using this approach shall solve most of the errors. | ||
|
|
||
| 3. Install R-devel, which is the most recent version of R from [https://svn.r-project.org/R/trunk/](svn) / [https://github.com/r-devel/r-svn](https://github.com/r-devel/r-svn) or [https://cran.r-project.org/bin/windows/base/rdevel.html](daily Windows build), and see if your bug still exists in R-devel (it may have been fixed very recently). | ||
|
|
||
| 4. Search on R-devel email list for messages with keywords related to your possible bug. If you find some related messages then read them to see if they clarify whether or not it is a bug. If you do not find any related messages, then please post a new message to R-devel. Your message should include (1) a brief description of the bug including current and expected behavior, (2) a minimal reproducible example. | ||
|
|
||
| ## What condition might not be a bug? | ||
|
|
||
| 1. In case the code is doing something unexpected, it may not necessarily be a bug. Carefully review the documentation of the function being called, and check whether the behaviour being exhibited on calling this function is the same as it was designed to do. | ||
|
|
||
| 2. Issues with [_seemingly_ identical numbers](https://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-doesn_0027t-R-think-these-numbers-are-equal_003f) not being equal (especially floating point numbers) are usually not bugs. | ||
|
|
||
| 3. If R is running slower than expected, then also it may not be a bug. Ask someone else to review your code in such a case. | ||
|
|
||
| 4. If some function is working, but it is not defined in the best generalised way, then consult someone to look over your code. This may perhaps not be a bug; instead, it might be an alternative way of writing the function. | ||
|
|
||
| ## Checking if a bug is already reported | ||
|
|
||
| The first step before filing a bug report is to see whether the problem has already been reported. Checking if the bug is reported will: | ||
|
|
||
| 1. Save time for you and the developers | ||
|
|
||
| 2. Help you see if the bug is already fixed for the next release | ||
|
|
||
| 3. Lead you to learn what needs to be done to fix it | ||
|
|
||
| 4. Determine if any additional information is needed | ||
|
|
||
| The sections that follow discuss where to check whether a bug is already reported. | ||
|
|
||
| ## Levels of contributing to bug / What do you do when you find a bug? | ||
|
|
||
| 1. [Report](#ReportBug) the bug (if it is not already reported). | ||
|
|
||
| 2. [Test](provide hyperlink to the section/chapter which discusses this also include comment 1 from getting started chapter) the bug. | ||
|
|
||
| 3. [Fix](hyperlink to the chapter on the lifecycle of a patch) the bug: Fixing a bug might require relatively more time. You may start a conversation about it on [BugZilla](https://bugs.r-project.org/bugzilla/index.cgi). This would require engagement with R Core team. | ||
|
|
||
| ## What are some places where you may find a bug? | ||
|
|
||
| You may find a bug in: | ||
|
|
||
| 1. In the [R-Core supported packages, their documentations, and/ or in the R language](#RCorePkgBug). | ||
|
|
||
| 2. In [packages and/or their documentations which are not supported by the R-Core](#nonRCorePkgBug). | ||
|
|
||
| ## How to report a bug? {#ReportBug} | ||
|
|
||
| Once you confirm a bug exists, you need to submit a bug report so that it gets fixed. | ||
|
|
||
| ### Bug in the R-Core supported packages, their documentations, and/ or in the R language {#RCorePkgBug} | ||
|
|
||
| 1. Packages that are supported by the R-Core are labelled with `Maintainer: R Core Team <R-core@r-project.org>`. One simple way to get the information from R is by running the `maintainer("package_name")` command. | ||
|
|
||
| 2. The bug report for R-Core supported packages, their documentations, and/ or a bug report for the R language itself can be submitted either to R's [Bugzilla](https://bugs.r-project.org/bugzilla/). In the future, we hope to have an option to report an issue to the [GitHub Mirror of R svn server](https://github.com/r-devel/r-svn/issues). | ||
|
|
||
| 3. If you want to submit the bug report using Bugzilla, please ensure that you have a Bugzilla account. To get a Bugzilla account, please send an e-mail to `bug-report-request@r-project.org` from the address that you want to use as your login. In this e-mail, briefly explain why you need an account. A volunteer shall then create a Bugzilla account and add you to R's Bugzilla members. | ||
|
|
||
| 4. Please ensure whether the bug is already fixed (in the upcoming changes in R) or reported (search for it from those already reported on Bugzilla, either on [search existing bug reports](https://bugs.r-project.org/bugzilla/query.cgi), may use the [advanced search](https://bugs.r-project.org/bugzilla/query.cgi?format=advanced) option here, or [show open bugs new-to-old](https://bugs.r-project.org/bugzilla/buglist.cgi?bug_file_loc_type=allwordssubstr&bug_status=NEW&bug_status=ASSIGNED&bug_status=CONFIRMED&bug_status=REOPENED&bug_status=UNCONFIRMED&bugidtype=include&chfieldto=Now&cmdtype=doit&emailassigned_to1=1&emailassigned_to2=1&emailcc2=1&emailreporter2=1&emailtype1=substring&emailtype2=substring&field0-0-0=noop&long_desc_type=substring&order=bugs.delta_ts%20desc&query_format=advanced&short_desc_type=allwordssubstr&type0-0-0=noop)). | ||
|
|
||
| ### Bug in the non R-Core supported packages and/or their documentations {#nonRCorePkgBug} | ||
|
|
||
| For packages that are not maintained by the R-Core, the bug reports can be submiited at, perhaps, an issues tracker url on GitHub/GitLab/R-Forge. To find if such an issues tracker is available, you can look at the package `DESCRIPTION` file first (e.g. using `packageDescription("package_name")`) to check if a url is provided in the `BugReports` field. If that is not available, then the package maintainer can be contacted (using `maintainer("package_name")`). In R running the function `bug.report(package = "package_name")` shall direct you to either the GitHub issue tracker of the package, or to the bug tracking web page, or towards composing an e-mail to the package maintainer. This function `bug.report` is disabled in RStudio, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on RStudio as well. Please ensure that the bug is not already reported or fixed before reporting it in any of the ways suggested above. | ||
|
|
||
| ## Good practices in reporting bugs / Expectations of a good bug report | ||
|
|
||
| If you follow the practices given below, you will come up with a good bug report which might make it easier for the maintainer(s) to fix the bug. | ||
|
|
||
| 1. Include a minimal reproducible example of the bug in your report. The maintainer should be able to quickly reproduce the bug on using the minimal example that you provide. Here is a [community wiki post](https://stackoverflow.com/questions/5963269/how-to-make-a-great-r-reproducible-example) on how to make a minimal reproducible example. | ||
|
|
||
| 2. Mention the software architecture on which the bug occurred. | ||
|
|
||
| 3. Use inbuilt data sets as far as possible. | ||
|
|
||
| In addition to the above, here are the [bug writing guidelines](https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html) on Bugzilla. The [bug reporting](https://www.r-project.org/bugs.html#writing-a-good-bug-report) documentation in R also the discusses practices to write a good bug report. | ||
|
|
||
| Once you have successfully reported a bug, you will likely receive an update each time an action is taken on the bug. On Bugzilla, the report may be given one of the following status: New, Assigned, Confirmed, Reopened, Unconfirmed. | ||
|
|
||
| ## Disagreement with a resolution on the bug tracker | ||
|
|
||
| As humans, there might be differences of opinions from time to time. What needs to be considered here is that, being respectful of the fact that care, thought, and volunteer time has gone into the resolution of the issue or bug. | ||
|
|
||
| If you take some time, then on reflection, the resolution steps may seem more reasonable than you initially thought. If you still feel that the resolution is incorrect, then raise a thoughtful question to the person who resolved it. If the issue was carefully thought about in the first place then is less likely to win any conversion of thought. | ||
|
|
||
| As a reminder, issues closed by a core developer on Bugzilla have already been carefully considered. Please do not reopen a closed issue. Although one can comment on a closed issue, if necessary. Every comment on an issue generates an email to every R-core member (unless they have the notifications disabled). So it would be best to be considerate while commenting on issues, especially in case of the closed issues or when you are commenting in pure agreement without adding anything beyond that to a discussion (the +1 type posts which are perfectly acceptable in other contexts). | ||
|
|
||
| ## Examples of Bug reports submitted on Bugzilla or R-devel mailing list | ||
|
|
||
| If you like to see how bugs are reported on Bugzilla, here are some examples: | ||
|
|
||
| 1. A [bug report](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17767) with a reproducible example, a patch, and a review. | ||
|
|
||
| 2. A [bug report](https://stat.ethz.ch/pipermail/r-devel/2019-May/077855.html) submitted by Kara Woo which was promptly fixed via the R-devel mailing list. (More information about the R-devel mailing list can be found [here](https://stat.ethz.ch/mailman/listinfo/r-devel)). | ||
|
|
||
| 3. A substring [bug reported](https://stat.ethz.ch/pipermail/r-devel/2019-February/077393.html) by Toby Dylan Hocking and fixed by Tomas Kalibera, Feb 2019 via the R-devel mailing list. | ||
|
|
||
| 4. A gregexpr [bug report and patch](https://stat.ethz.ch/pipermail/r-devel/2019-February/077315.html) submitted by Toby Dylan Hocking and merged by Tomas Kalibera, Feb 2019 via the R-devel mailing list. | ||
|
|
||
| ## See also | ||
|
|
||
| 1. [Reporting a bug](https://www.r-project.org/bugs.html) | ||
|
|
||
| 2. [R FAQ on bugs](https://mac.r-project.org/man/R-FAQ.html#R-Bugs) | ||
|
|
||
| 3. [Bugzilla guidelines of reporting a bug](https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Reviewing Bugs | ||
|
|
||
| ## How you can help to review bug reports? | ||
|
|
||
| After understanding where bugs are reported in R (Bugzilla) or in other projects (GitHub/GitLab/R-Forge), a great way to contribute is reviewing bug reports. | ||
|
|
||
| Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of R packages and existing bug reports are being updated. Every bug report needs to be reviewed to make sure various things are in proper order. You can help with this process of reviewing bugs. | ||
|
|
||
| ### Preparing to review bug reports | ||
|
|
||
| If you want to review bug reports on Bugzilla, you are required to have a Bugzilla account. To get a Bugzilla account send an e-mail to `bug-report-request@r-project.org` from the address you want to use as your Bugzilla login. Briefly explain why you want a Bugzilla account and a volunteer will add you to R's Bugzilla members. More details on how you can review a bug report are available on this [blog](https://developer.r-project.org/Blog/public/2019/10/09/r-can-use-your-help-reviewing-bug-reports/) | ||
|
|
||
| ## Classifying bug reports | ||
|
|
||
| A good bug report is the one which: | ||
|
|
||
| 1. Explains clearly how to reproduce the bug. | ||
|
|
||
| 2. Includes the version of R, the machine architecture, and the operating system platform on which the bug occurred. | ||
|
|
||
| Relevant details should be a part of a good bug report. You can help with the following tasks once you have some R programming experience: | ||
|
|
||
| 1. Reproducing the bug: If you see a bug report which does not clearly explain how to reproduce it, you can try reproducing the bug and eventually make things easier for the core developer(s) and/or package maintainer(s). | ||
|
|
||
| 2. Checking different binary builds: Check whether the bug occurs on a different binary build of R. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of R. | ||
|
|
||
| 3. Writing a unit test: If the bug report lacks a unit test that should be a part of R's test suite, then you can help with providing it. | ||
|
|
||
| These helpful tasks allow the Core developers and/ or maintainers to classify a bug report properly, so that the bug can be handled in a timely fashion. | ||
|
|
||
| ## How to find a bug report or an issue to review? | ||
|
|
||
| 1. You may search old bug reports or issues that could be closed. Old bug reports may no longer be valid or may include a patch that is ready to be committed, but no one has had the time to review and commit. | ||
|
|
||
| 2. You might also want to search for issues in topics in which you have a working knowledge. When on Bugzilla you can use the advanced search to find specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability). | ||
|
|
||
| ## Example of a bug review submitted on Bugzilla | ||
|
|
||
| If you would like to see how bugs are reviewed on Bugzilla, [here](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=16542) is an example where an old bug report is being reviewed. It is tested to see if it was still an issue and a few ways are proposed to resolve the issue. | ||
|
|
||
| **Note**: | ||
|
|
||
| There is a `#bugreports-for-review` channel on the [R-devel slack](https://r-devel.slack.com/) where you can share your bug report(s) for review/feedback before submitting to Bugzilla. This can help with checking that it really is a bug, that you have included the important information and excluded redundant information. | ||
|
|
||
| ## See also | ||
|
|
||
| 1. [Reviewing bug reports: Blog](https://developer.r-project.org/Blog/public/2019/10/09/r-can-use-your-help-reviewing-bug-reports/) |