Bug Tracking

11-bug_tracking.Rmd

@@ -1,23 +1,127 @@
-# Bug Tracking
-
-## Using the Bug Tracker (Bugzilla)
-
-### Checking if a bug already exists
-
-### Reporting a bug
-
-### Understanding the issue’s progress and status
-
-## Disagreement With a Resolution on the Bug Tracker
-
-## Helping Triage Issues
-
-### Classifying Reports
-
-### Reviewing Patches
-
-### Finding an Issue You Can Help With
-
-## Gaining the “Developer” Role on the Bug Tracker
-
-## The Meta Tracker
+# Bug Tracking
+
+## What is a bug in $\textsf{R}$ ?
+
+You may find a bug in $\textsf{R}$ if:
+
+
+1. The $\textsf{R}$ session terminates unexpectedly, or there is a segmentation fault, it might be a bug, 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.
+
+$\textbf{Note}$:
+When you are in doubt that there is a bug:
+
+1. Make sure whether the bug appears in a clean session of $\textsf{R}$. Many a times, there are variables/commands/functions stored in history which might causes issues. Hence, check in a clean session. To do so, launch $\textsf{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.
+
+## What may 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 $\textit{seemingly}$ identical numbers not being equal (especially floating point numbers) are usually not bugs. 
+
+3. If $\textsf{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 some 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) 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 either on BugZilla (link here) or on the GitHub mirror (link here). This would require engagement with $\textsf{R}$ Core team.
+
+## What are some places where you may find a bug?
+
+You may find a bug in:
+
+1. The [documentation of this guide](#GuideDocBug).
+
+2. In the [$\textsf{R}$ Core-supported packages and/or their documentations](#RCorePkgBug).
+
+3. In the [$\textsf{R}$ language](#RLangBug).
+
+4. In [packages and/or their documentations which are not supported by the $\textsf{R}$ Core](#nonRCorePkgBug).
+
+## How to report a bug? {#ReportBug}
+
+Once you are confirmed that there is a bug, you need to submit a report so that it gets fixed.
+
+### Bug in the documentation of this guide {#GuideDocBug}
+
+1. If there is a bug in the documentation of this guide, then please report it as an issue at https://github.com/forwards/rdevguide/issues. 
+
+2. Please go through the $\textit{closed}$ issues to check if the bug is already reported and fixed. Otherwise, please check in the $\textit{open}$ issues to see if it is reported. If it is not recorded at either of these places, then please submit a new issue.
+
+### Bug in the $\textsf{R}$ Core-supported packages and/or their documentations {#RCorePkgBug}
+
+1. Packages that are supported by the $\textsf{R}$ Core are labelled with `Maintainer: R Core Team <R-core@r-project.org>`. You can check this label either by running `maintainer("package_name")` or by looking at the `Maintainer` field in the output when the command `packageDescription("package_name")` is run in $\textsf{R}$.
+
+2. The bug report for $\textsf{R}$ Core-supported packages and/or their documentations can be submitted either to $\textsf{R}$'s [Bugzilla](https://bugs.r-project.org/bugzilla/) or as 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 $\textsf{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)). If you are submitting the report as an issue on the GitHub Mirror, then please check the currently $\textit{open}$ and $\textit{closed}$ issues first, to find if it is already reported or resolved. Do not submit a report in such a case. 
+
+### Bug in the $\textsf{R}$ Language {#RLangBug}
+
+1. If there is a bug in the $\textsf{R}$ language itself, then you need to report using the same procedure and precautions as explained [above](#RCorePkgBug).
+
+### Bug in the non $\textsf{R}$ Core-supported packages and/or their documentations {#nonRCorePkgBug}
+
+1. For packages that are not maintained by the $\textsf{R}$ Core, the bug reports are usually submitted to their maintainer(s). You can find who is the package maintainer by running either of the commands `maintainer("package_name")` or `packageDescription("package_name")`.
+
+2. In $\textsf{R}$ the running 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 $\textbf{RStudio}$.
+
+3. Please ensure that your 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.
+
+2. Mention the software architecture on which the bug occurred. 
+
+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, we are 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 the GitHub Mirror have already been carefully considered. Please do not reopen a closed issue.
+
+## 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)