From f0f40630d5b88d983e769c31ad56ff66f67731a8 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 15 Mar 2021 18:20:47 +0530 Subject: [PATCH 01/48] Using BugZilla From b5c6c01a39c99c7529b5d959c5e1a6bf231f31f6 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 29 Mar 2021 19:10:34 +0530 Subject: [PATCH 02/48] bug_tracking --- 11-bug_tracking.Rmd | 120 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 97 insertions(+), 23 deletions(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 72e97b2..8d092a4 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -1,23 +1,97 @@ -# 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}$ ? + +Following are some situations where you may find a bug in $\textsf{R}$: + +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. + +## Levels of contributing to bug / What do you do when you find a bug? + +1. [Report](#ReportBug) the bug. + +2. [Test](provide hyperlink to the section/chapter which discusses this) the bug. + +3. [Fix](provide hyperlink to the section/chapter which discusses this) 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. + +4. In packages and/or their documentations which are not supported by the $\textsf{R}$ Core. + +## Using the Bug Tracker (BugZilla or GitHub Mirror) +## 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 `. 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. + + +## (good) Social practices in reporting bugs / Expectations of a (good) bug report + +### 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 + +## Python Dev Guide + +## References From 07f0c510b46771b3f9d1c2221b0980aeec844344 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 29 Mar 2021 19:13:38 +0530 Subject: [PATCH 03/48] bug tracking --- 02-getting_started.Rmd | 37 +++----------------- 04-lifecycle_of_a_Patch.Rmd | 68 +++++++++++++++++++++---------------- 2 files changed, 44 insertions(+), 61 deletions(-) diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd index 5ca36d5..75b2cc7 100755 --- a/02-getting_started.Rmd +++ b/02-getting_started.Rmd @@ -22,17 +22,9 @@ To install $\textsf{R}$ in Windows follow these steps: ## General instructions -1. The $\textsf{R}$ executable downloaded by following the above steps, is the binary distribution of `R-x.y.z`, which can run on Windows XP and above versions (including 64-bit versions of Windows). It can run on ix86 and x86_64 chips. +1. If you install the latest version or R-patched or R-devel, it will not over-write the previous installation(s) in your Windows machine. -2. There are two versions of the $\textsf{R}$ executable, the 32-bit version (in `R-x.y.z\bin\i386`) and the 64-bit version (in `R-x.y.z\bin\x64`). On the 32-bit versions of Windows, by default only the former gets installed, whereas on the 64-bit versions, both get installed. - -3. If there is already a previous version of R installed in your system and you want to retain the packages installed in it, then uninstall the previous version of $\textsf{R}$ (from the Control Panel) and install the new one. In the new installation, copy any installed packages to the library folder and run `update.packages(checkBuilt=TRUE, ask=FALSE)` in the new $\textsf{R}$. - -4. If there are different versions of R installed, then they are present in parallel folders. Hence, earlier versions can also be retained if you wish to keep them. - -5. When there is a change in the minor version of $\textsf{R}$ (say, from 4.0.3 to 4.1.0), then the library names (folder `R\win-library\x.y` of your home directory, `R\win64-library\x.y` on 64-bit builds), will need to be updated too. For doing this, copy (say) `R\win-library\4.0` to `R\win-library\4.1` and then run the `update.packages(checkBuilt=TRUE, ask=FALSE)` command. - -6. Daily [tarballs](https://stat.ethz.ch/R/daily/) are available for the patched version of the current release (`r-patched`), and the development version of the current release (`r-devel`). The same are also available via the [R Subversion repository](https://svn.R-project.org/R/) +2. Daily [tarballs](https://stat.ethz.ch/R/daily/) are available for the patched version of the current release (`r-patched`), and the development version of the current release (`r-devel`). The same are also available via the [R Subversion repository](https://svn.R-project.org/R/) ## Building $\textsf{R}$ and $\textsf{R}$ packages @@ -44,31 +36,12 @@ To install $\textsf{R}$ in Windows follow these steps: ### How to setup `RTools`? -1. The executable version of `RTools` that is specific to your requirements can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. - -2. After completing the installation, you need to put the location of the RTools $\textit{make}$ $\textit{utilities}$ on the `PATH`. For doing this, exceute the following commands in $\textsf{R}$: - -```{r, results='hide'} -writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron") -``` - -Restart $\textsf{R}$ now. Verify that $\textit{make}$ can be found using the following command. (The output of the command should show the path where you installed `RTools`): - -```{r, results='hide'} -Sys.which("make") -## "C:\\rtools40\\usr\\bin\\make.exe" -``` - -If the above works, then try installing an $\textsf{R}$ package from source: - -```{r, results='hide'} -## install.packages("jsonlite", type = "source") ## An example -``` +1. The latest version of `RTools` can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure). -If you are successful in installing an $\textsf{R}$ package from source, then the setup for `RTools` is completed. +2. Don't forget to add `RTools` to the path as documented on the download page. ### How to build $\textsf{R}$? To build $\textsf{R}$ for Windows using `RTools` follow the instructions in this [readme](https://github.com/r-windows/r-base#readme) file. -## References (chapterwise or at the end of the guide?) +## References diff --git a/04-lifecycle_of_a_Patch.Rmd b/04-lifecycle_of_a_Patch.Rmd index b5917d0..a9fd685 100644 --- a/04-lifecycle_of_a_Patch.Rmd +++ b/04-lifecycle_of_a_Patch.Rmd @@ -1,29 +1,39 @@ -# Lifecycle of a Patch - -## Introduction - -## Quick Guide - -## Step-by-step Guide - -### Resolving Merge Confilcts - -## Making Good PRs - -## Making Good Commits - -## Licensing - -## Submitting - -## Converting an Existing Patch - -## Reviewing - -### How to Review a Pull Request - -## Leaving a Pull Request Review - -## Committing/Rejecting - -## Crediting +# Lifecycle of a Patch + +#### Include following levels of testing: +## 1. Contribute to a test +## 2. Report a bug fix +## 3. Add a new feature (or test) +#### For test coverage, no standard ways. there is perhaps a 'cover' package +#### Submit more bugs, it will cause more testing + +#### A tips and tricks section: for instance, use a text editor, notepad, emacs for testing, emacs distribution, configurations of emacs which might be useful, use RStudio editor + + +## Introduction + +## Quick Guide + +## Step-by-step Guide + +### Resolving Merge Confilcts + +## Making Good PRs + +## Making Good Commits + +## Licensing + +## Submitting + +## Converting an Existing Patch + +## Reviewing + +### How to Review a Pull Request + +## Leaving a Pull Request Review + +## Committing/Rejecting + +## Crediting From 0a124517e59b0c55da2ba9305da149f259bf9808 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 03:02:29 +0530 Subject: [PATCH 04/48] Delete 04-lifecycle_of_a_Patch.Rmd --- 04-lifecycle_of_a_Patch.Rmd | 39 ------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 04-lifecycle_of_a_Patch.Rmd diff --git a/04-lifecycle_of_a_Patch.Rmd b/04-lifecycle_of_a_Patch.Rmd deleted file mode 100644 index a9fd685..0000000 --- a/04-lifecycle_of_a_Patch.Rmd +++ /dev/null @@ -1,39 +0,0 @@ -# Lifecycle of a Patch - -#### Include following levels of testing: -## 1. Contribute to a test -## 2. Report a bug fix -## 3. Add a new feature (or test) -#### For test coverage, no standard ways. there is perhaps a 'cover' package -#### Submit more bugs, it will cause more testing - -#### A tips and tricks section: for instance, use a text editor, notepad, emacs for testing, emacs distribution, configurations of emacs which might be useful, use RStudio editor - - -## Introduction - -## Quick Guide - -## Step-by-step Guide - -### Resolving Merge Confilcts - -## Making Good PRs - -## Making Good Commits - -## Licensing - -## Submitting - -## Converting an Existing Patch - -## Reviewing - -### How to Review a Pull Request - -## Leaving a Pull Request Review - -## Committing/Rejecting - -## Crediting From a7c660df2464840c6595ecfc7d2de2dea0ee0dfa Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 03:06:39 +0530 Subject: [PATCH 05/48] references added --- 02-getting_started.Rmd | 10 ++++++- 11-bug_tracking.Rmd | 64 +++++++++++++++++++++++++++++------------ rdevguide.rds | Bin 1087 -> 303 bytes 3 files changed, 55 insertions(+), 19 deletions(-) diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd index 75b2cc7..90fc57c 100755 --- a/02-getting_started.Rmd +++ b/02-getting_started.Rmd @@ -44,4 +44,12 @@ To install $\textsf{R}$ in Windows follow these steps: To build $\textsf{R}$ for Windows using `RTools` follow the instructions in this [readme](https://github.com/r-windows/r-base#readme) file. -## References +## See also + +1. [CRAN official website](https://cran.r-project.org) + +2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html) + +3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) + +4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 8d092a4..36048b5 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -30,13 +30,27 @@ When you are in doubt that there is a bug: 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. +1. [Report](#ReportBug) the bug (if it is not alreasy reported). 2. [Test](provide hyperlink to the section/chapter which discusses this) the bug. -3. [Fix](provide hyperlink to the section/chapter which discusses this) 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. +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? @@ -46,11 +60,10 @@ You may find a bug in: 2. In the [$\textsf{R}$ Core-supported packages and/or their documentations](#RCorePkgBug). -3. In the $\textsf{R}$ language. +3. In the [$\textsf{R}$ language](#RLangBug). -4. In packages and/or their documentations which are not supported by the $\textsf{R}$ Core. +4. In [packages and/or their documentations which are not supported by the $\textsf{R}$ Core](#nonRCorePkgBug). -## Using the Bug Tracker (BugZilla or GitHub Mirror) ## 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. @@ -69,29 +82,44 @@ Once you are confirmed that there is a bug, you need to submit a report so that 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 -## (good) Social 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. -### Checking if a bug already exists +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. -### Reporting a bug +2. Mention the software architecture on which the bug occurred. -### Understanding the issue’s progress and status +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. -## Disagreement With a Resolution on the Bug Tracker +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. -## Helping Triage Issues +## Disagreement with a resolution on the bug tracker -### Classifying Reports +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. -### Reviewing Patches +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. -### Finding an Issue You Can Help With +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. -## Gaining the “Developer” Role on the Bug Tracker +## See also -## The Meta Tracker +1. [Reporting a bug](https://www.r-project.org/bugs.html) -## Python Dev Guide +2. [R FAQ on bugs](https://mac.r-project.org/man/R-FAQ.html#R-Bugs) -## References +3. [Bugzilla guidelines of reporting a bug](https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html) diff --git a/rdevguide.rds b/rdevguide.rds index 82dde4182c8e10f9149f3a79ecb9ca2490b9e3fb..9b9845937f33a7ebe573724d3b255bddef5239bc 100644 GIT binary patch literal 303 zcmV+~0nq**iwFP!00000291*2PQx$^hP`e@3^WNb$~Zhj5v@StelIZXin}N@Zi&_w zsr5L#Ji~3p+N9gGn?$ky-~N*L^$Y-pFsfFU7dV+Og77&6aHf3XkaNNNfE8ojPj#;F z`yo>RBc~G|uX0TyLy~-`j9?35onk4JF8I)`cwSc&b=vYwbWT`gsI;UiY4|1$$(rJq z8V7zYRPQnL6C~1kB1)14q1ti}HYTRCv8vzn&0WNyt-ssR%s{i$PkyRnjDDgN#YZfp zSV)TAYqfES%OLRI)`_4(Mk_9U{0%(Ic@TeQx7q)!S3&3(_^I)$D$1tvc&1s;dywk3 z-^$=JhQ-ZgwjC1pf9jecS+b)ET<`d&HhaJCUs}o3eyKL)^>LRC>K}{$rvPOG008tJ BmHq$# literal 1087 zcmV-F1iA$&YP&dp}yxZ`+z~Bd_BWaP*+Zy4%;c@dPaAL=dPr)M{`}ipB7#9QLYjnQJ+B z0SY=Jc!diB`3xd>gA|_E(p!$5#Fs!+jG5O!EQ3oy>sQj3uHfR5qn~d; z#BeV@?#A-eOY#Lg%E5x?0rk>R^_jT>2xGFSV|8;Ike#EBs%Iu7*TBjFSU2l{nb525 zHg}kO1(=&|QSnMbGv9L&*y+Y@47cHfGzKWk>dwreniD-Qvw}{Cn>}$MxQ)I`6M*N4 z9~)FlJSgCb1oiiM@-*hR?bO#?uEWny}W zCTCQwpu{Mk{fs)Qp1C=RLAGM3q*yajRIDVGYj%cBEeFia9YAguP9{l1iZ!pGMK*$V7tkr^3ZrsS?+kcO zkdkvk0(#o{4xlX;widx>`bHlY+tbZ_Tk&m^^XBMvmz6h%M{X+J2%YX= zyp80C-K^A#Plrm{XKnsxr9>}bv){={uB^OqQK3fUz`~`J6{s$Kf*ERnW F001Y)8BG8H From d1663d24a19bc3d874feb347834c33c8d332a966 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 03:48:25 +0530 Subject: [PATCH 06/48] Delete 02-getting_started.Rmd --- 02-getting_started.Rmd | 55 ------------------------------------------ 1 file changed, 55 deletions(-) delete mode 100755 02-getting_started.Rmd diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd deleted file mode 100755 index 90fc57c..0000000 --- a/02-getting_started.Rmd +++ /dev/null @@ -1,55 +0,0 @@ -# Getting Started - -These instructions cover how to install $\textsf{R}$ in Windows. The tools required to build $\textsf{R}$ and $\textsf{R}$ packages in Windows are also discussed. - -## Installing $\textsf{R}$ - -To install $\textsf{R}$ in Windows follow these steps: - -1. Go to https://cran.r-project.org. - -2. Select `Download R for Windows`. You will be directed to a page which shows `Subdirectories` for installing R on Windows. - -3. Select `base` subdirectory. Alternatively, you can select `install R for the first time`, it leads to the same page. The current official stable release distribution of $\textsf{R}$ can be downloaded from here. (Along with the link to the current official stable release, links to the development snapshot build and to the previous releases, are also available on this page). - -4. This distribution is distributed as an installer `R-x.y.z-win.exe`. The `x.y.z` in the $\textsf{R}$ system version represent the major, minor, and patchlevel numbers, respectively. - -5. This has to be run in the Windows-style installer. - -6. Select the language while installing, read the public license information, and select destination location to the start the installation. You will be prompted to select components at this stage: `User installation`, `32-bit User installation`, `64-bit User installation`, or `Custom installation`. The default option may be opted for the questions from this step onwards. - -7. Complete the installation. - -## General instructions - -1. If you install the latest version or R-patched or R-devel, it will not over-write the previous installation(s) in your Windows machine. - -2. Daily [tarballs](https://stat.ethz.ch/R/daily/) are available for the patched version of the current release (`r-patched`), and the development version of the current release (`r-devel`). The same are also available via the [R Subversion repository](https://svn.R-project.org/R/) - -## Building $\textsf{R}$ and $\textsf{R}$ packages - -### What tools you need to build $\textsf{R}$ from source on Windows? - -1. `RTools` is the [subdirectory](https://cran.r-project.org/bin/windows/Rtools/) which you want to build $\textsf{R}$ or your own $\textsf{R}$ package(s) on Windows. - -2. You also need a distribution of $\LaTeX$ installed for building $\textsf{R}$ and checking packages. The `MiKTeX` distribution of $\LaTeX$ that is used on CRAN can be downloaded from https://miktex.org. - -### How to setup `RTools`? - -1. The latest version of `RTools` can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure). - -2. Don't forget to add `RTools` to the path as documented on the download page. - -### How to build $\textsf{R}$? - -To build $\textsf{R}$ for Windows using `RTools` follow the instructions in this [readme](https://github.com/r-windows/r-base#readme) file. - -## See also - -1. [CRAN official website](https://cran.r-project.org) - -2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html) - -3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) - -4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/) From 169abf0c30f0fcc021339c9859d02c358e5d0ec6 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 18:14:19 +0530 Subject: [PATCH 07/48] add chapter on reviewing bug reports --- 12-reviewing_bugs.Rmd | 119 +++++++++++++++++++++++++++--------------- 1 file changed, 78 insertions(+), 41 deletions(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 0254a05..00dc919 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -1,41 +1,78 @@ -# Reviewing Bugs - -## Python triage team - -## Becoming a member of the Python triage team - -### GitHub Labels for PRs - -## Fields in the Bug Tracker - -### Title - -### Type - -### Stage - -### Components - -### Versions - -### Priority - -### Keywords - -### Nosy List - -### Assigned To - -### Dependencies - -### Superseder - -### Status - -### Resolution - -### Mercurial Repository - -## Generating Special Links in a Comment - -## Checklist for Triaging +# Reviewing Bugs + +## How you can help to review bug reports? + +Once you are aware where bugs are reported in $\textsf{R}$, a great way to contribute is to help reviewing the bug reports. + +Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of $\textsf{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. + +Note: 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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{R}$'s Bugzilla members. + +### Classifying bug reports + +A good bug report is the one which: + +1. Clearly explains the bug so that it can be reproduced. + +2. Includes the version of $\textsf{R}$, the machine architecture, and the operating system platform on which the bug occurred. + +These are the relevant details that should be a part of a good bug report. You can help with these things once you have experience developing for $\textsf{R}$: + +1. Reproducing the bug: If you see a bug report which does not clearly explains 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. Check whether the bug occurs on a different version of $\textsf{R}$. It is helpful to know if a bug is not only affecting the + +### Reviewing Patches + +### Finding an Issue You Can Help With + +## Gaining the “Developer” Role on the Bug Tracker + +## The Meta Tracker + +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/) + + +## Python triage team + +## Becoming a member of the Python triage team + +### GitHub Labels for PRs + +## Fields in the Bug Tracker + +### Title + +### Type + +### Stage + +### Components + +### Versions + +### Priority + +### Keywords + +### Nosy List + +### Assigned To + +### Dependencies + +### Superseder + +### Status + +### Resolution + +### Mercurial Repository + +## Generating Special Links in a Comment + +## Checklist for Triaging + +## 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/) From cc44c61e01e0c14b0a3b2e749e674771b03a21fb Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 18:23:57 +0530 Subject: [PATCH 08/48] Update 11-bug_tracking.Rmd MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lluís --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 36048b5..9e021fe 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -2,7 +2,8 @@ ## What is a bug in $\textsf{R}$ ? -Following are some situations where you may find 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: From 86754255e32264f400ed6ac0da757f2b29f18c05 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 5 Apr 2021 18:24:07 +0530 Subject: [PATCH 09/48] Update 11-bug_tracking.Rmd MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lluís --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 9e021fe..6e026e9 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -47,7 +47,8 @@ The sections that follow discuss where to check whether a bug is already reporte ## Levels of contributing to bug / What do you do when you find a bug? -1. [Report](#ReportBug) the bug (if it is not alreasy reported). +1. [Report](#ReportBug) the bug (if it is not already reported). + 2. [Test](provide hyperlink to the section/chapter which discusses this) the bug. From 3356e0df63227b95690ab00ac5a3f0f0734b3600 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 04:41:48 +0530 Subject: [PATCH 10/48] section on classifying reports added --- 12-reviewing_bugs.Rmd | 60 ++++++++----------------------------------- 1 file changed, 11 insertions(+), 49 deletions(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 00dc919..ba3d89f 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -6,7 +6,10 @@ Once you are aware where bugs are reported in $\textsf{R}$, a great way to contr Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of $\textsf{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. -Note: 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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{R}$'s Bugzilla members. +Note: +1. 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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{R}$'s Bugzilla members. + +2. 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 @@ -18,60 +21,19 @@ A good bug report is the one which: These are the relevant details that should be a part of a good bug report. You can help with these things once you have experience developing for $\textsf{R}$: -1. Reproducing the bug: If you see a bug report which does not clearly explains 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. Check whether the bug occurs on a different version of $\textsf{R}$. It is helpful to know if a bug is not only affecting the - -### Reviewing Patches - -### Finding an Issue You Can Help With - -## Gaining the “Developer” Role on the Bug Tracker - -## The Meta Tracker - -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/) - - -## Python triage team - -## Becoming a member of the Python triage team - -### GitHub Labels for PRs - -## Fields in the Bug Tracker - -### Title - -### Type - -### Stage - -### Components - -### Versions - -### Priority - -### Keywords - -### Nosy List - -### Assigned To - -### Dependencies +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). -### Superseder +2. Check whether the bug occurs on a different binary build of $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. -### Status +3. Writing a unit test: If the bug report lacks a unit test that should be a part of $\textsf{R}$'s test suite, then you can help with providing it. -### Resolution +This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. -### Mercurial Repository +### How to find a bug report or an issue that you can help with? -## Generating Special Links in a Comment +1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. -## Checklist for Triaging +2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. ## See also From 48aa515102bfd8daddcc21045be57eda8ad0c153 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 04:43:23 +0530 Subject: [PATCH 11/48] Delete 11-bug_tracking.Rmd --- 11-bug_tracking.Rmd | 125 -------------------------------------------- 1 file changed, 125 deletions(-) delete mode 100644 11-bug_tracking.Rmd diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd deleted file mode 100644 index 36048b5..0000000 --- a/11-bug_tracking.Rmd +++ /dev/null @@ -1,125 +0,0 @@ -# Bug Tracking - -## What is a bug in $\textsf{R}$ ? - -Following are some situations where you may find a bug in $\textsf{R}$: - -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 alreasy 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 `. 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) From b1b64590af48f9a80f9165545b040f906a0c938b Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:37:24 +0530 Subject: [PATCH 12/48] wording changes to good bug report Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index ba3d89f..3d3d9b8 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -15,7 +15,8 @@ Note: A good bug report is the one which: -1. Clearly explains the bug so that it can be reproduced. +1. Explains clearly how to reproduce the bug. + 2. Includes the version of $\textsf{R}$, the machine architecture, and the operating system platform on which the bug occurred. From 0b32c40378feff1c941a590b1c7e140585fe0ce1 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:38:21 +0530 Subject: [PATCH 13/48] wording changes--how you can help Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 3d3d9b8..afb21ac 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -2,7 +2,7 @@ ## How you can help to review bug reports? -Once you are aware where bugs are reported in $\textsf{R}$, a great way to contribute is to help reviewing the bug reports. +After understanding where bugs are reported in $\textsf{R}$ (Bugzilla) or in other projects (GitHub), 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 $\textsf{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. From e0a4ddc2de5e81b849e56c3f380efdeda055c608 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:38:56 +0530 Subject: [PATCH 14/48] sub-sub-section title Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index afb21ac..4b939d2 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -6,7 +6,8 @@ After understanding where bugs are reported in $\textsf{R}$ (Bugzilla) or in oth Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of $\textsf{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. -Note: +### Preparing to review bug reports + 1. 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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{R}$'s Bugzilla members. 2. 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/) From eeeb0004603faf2cf97b9edda5204a908bf9bfd4 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:39:40 +0530 Subject: [PATCH 15/48] Bugzilla login Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 4b939d2..e37ea7f 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -8,7 +8,8 @@ Around the clock, new bug reports are being submitted on Bugzilla or the bug tra ### Preparing to review bug reports -1. 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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{R}$'s Bugzilla members. +1. 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 $\textsf{R}$'s Bugzilla members. + 2. 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/) From 2f8cc156e87c66e1248f404aa74e055f38d6e65e Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:40:36 +0530 Subject: [PATCH 16/48] wording changes -- relevant details Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index e37ea7f..bd471d9 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -22,7 +22,8 @@ A good bug report is the one which: 2. Includes the version of $\textsf{R}$, the machine architecture, and the operating system platform on which the bug occurred. -These are the relevant details that should be a part of a good bug report. You can help with these things once you have experience developing for $\textsf{R}$: +Relevant details should be a part of a good bug report. You can help with the following tasks once you have some experience developing for $\textsf{R}$: + 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). From b10e01f08d6803325897ca10e2db191fdc1c0f1a Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:41:07 +0530 Subject: [PATCH 17/48] checking different binary builds Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index bd471d9..d99e0b4 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -27,7 +27,8 @@ Relevant details should be a part of a good bug report. You can help with the fo 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. Check whether the bug occurs on a different binary build of $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. +2. Checking different binary builds: Check whether the bug occurs on a different binary build of $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. + 3. Writing a unit test: If the bug report lacks a unit test that should be a part of $\textsf{R}$'s test suite, then you can help with providing it. From 942556ea90cfb7e649c5f0d71c5581ce7ab29181 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:41:32 +0530 Subject: [PATCH 18/48] helpful tasks Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index d99e0b4..4d4681b 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -32,7 +32,8 @@ Relevant details should be a part of a good bug report. You can help with the fo 3. Writing a unit test: If the bug report lacks a unit test that should be a part of $\textsf{R}$'s test suite, then you can help with providing it. -This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. +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 that you can help with? From 8c32c152df3e3236886f4ecbeb75d4b5b9665b0c Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:42:38 +0530 Subject: [PATCH 19/48] wording changes -- searching bug reports Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 4d4681b..4fb73ea 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -39,7 +39,8 @@ These helpful tasks allow the Core developers and/ or maintainers to classify a 1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. -2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. +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). + ## See also From ad15645a2d4d43b5ffc69ac101920cdace91c380 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:43:32 +0530 Subject: [PATCH 20/48] older bug reports Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 4fb73ea..1ed5468 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -37,7 +37,8 @@ These helpful tasks allow the Core developers and/ or maintainers to classify a ### How to find a bug report or an issue that you can help with? -1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. +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). From d2c7b01f2c1b17f1da6b606d3542ccb4b2d52a2d Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:44:13 +0530 Subject: [PATCH 21/48] review help Co-authored-by: Carol Willing --- 12-reviewing_bugs.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index 1ed5468..bf999a2 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -35,7 +35,8 @@ Relevant details should be a part of a good bug report. You can help with the fo 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 that you can help with? +### 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. From f7ebad288adc658423cc31ea77897348e9107d87 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:46:49 +0530 Subject: [PATCH 22/48] prior to reporting issue Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 6e026e9..885540f 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -74,7 +74,8 @@ Once you are confirmed that there is a bug, you need to submit a report so that 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. +2. Prior to reporting the issue, 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 found at either of these places, then please submit a new issue. + ### Bug in the $\textsf{R}$ Core-supported packages and/or their documentations {#RCorePkgBug} From 00d0958872b07f1d026a7c06e128a6d6ae4cbc25 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:47:13 +0530 Subject: [PATCH 23/48] not a bug condition Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 885540f..ef537f3 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -21,7 +21,8 @@ When you are in doubt that there is a bug: 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? +## 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. From 80143289da92af7a400c49e33145d917bd0b6f60 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:47:53 +0530 Subject: [PATCH 24/48] issue in a clean R session Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index ef537f3..bbd5802 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -17,7 +17,8 @@ You may find a bug in $\textsf{R}$ if: $\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. +1. Make sure whether the bug appears in a clean session of $\textsf{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 $\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. From 93bcee464b1a4e6e10b2b5b6bf823643b71dff5e Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:48:41 +0530 Subject: [PATCH 25/48] confirm a bug exists Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index bbd5802..17eae38 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -70,7 +70,8 @@ You may find a bug in: ## 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. +Once you confirm a bug exists, you need to submit a bug report so that it gets fixed. + ### Bug in the documentation of this guide {#GuideDocBug} From 15ac98642f604b8e686e77de3470043a3d09622f Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:50:07 +0530 Subject: [PATCH 26/48] consult someone to look over your code Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 17eae38..e561846 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -31,7 +31,8 @@ When you are in doubt that there is a bug: 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. +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 From 419324a56c6aad4e0d0871b011229532d2aaded5 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 6 Apr 2021 12:57:56 +0530 Subject: [PATCH 27/48] github mirror of R svn server Co-authored-by: Carol Willing --- 11-bug_tracking.Rmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index e561846..3728a96 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -85,7 +85,8 @@ Once you confirm a bug exists, you need to submit a bug report so that it gets f 1. Packages that are supported by the $\textsf{R}$ Core are labelled with `Maintainer: R Core Team `. 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). +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/). 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 $\textsf{R}$'s Bugzilla members. From 25eef81fe33db2357770cb1eb895b36c9d14e3cc Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sun, 11 Apr 2021 06:00:42 +0530 Subject: [PATCH 28/48] minor edits --- 12-reviewing_bugs.Rmd | 32 +++++++++++--------------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd index bf999a2..035a89f 100644 --- a/12-reviewing_bugs.Rmd +++ b/12-reviewing_bugs.Rmd @@ -2,47 +2,37 @@ ## How you can help to review bug reports? -After understanding where bugs are reported in $\textsf{R}$ (Bugzilla) or in other projects (GitHub), a great way to contribute is reviewing bug reports. +Once you are aware where bugs are reported in $\textsf{R}$, a great way to contribute is to help reviewing the bug reports. Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of $\textsf{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 +Note: -1. 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 $\textsf{R}$'s Bugzilla members. +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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{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/) - -2. 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 +## Classifying bug reports A good bug report is the one which: -1. Explains clearly how to reproduce the bug. - +1. Clearly explains the bug so that it can be reproduced. 2. Includes the version of $\textsf{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 experience developing for $\textsf{R}$: - +These are the relevant details that should be a part of a good bug report. You can help with these things once you have $\textsf{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 $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. - +2. Check whether the bug occurs on a different binary build of $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. 3. Writing a unit test: If the bug report lacks a unit test that should be a part of $\textsf{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. +This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. +## How to find a bug report or an issue that you can help with? -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). +1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. +2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. ## See also From 3636c6b49aecdad8e390912e5ddc6b1be87ac0e4 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sun, 11 Apr 2021 14:07:58 +0530 Subject: [PATCH 29/48] minor edits --- 02-getting_started.Rmd | 61 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 02-getting_started.Rmd diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd new file mode 100644 index 0000000..b898b27 --- /dev/null +++ b/02-getting_started.Rmd @@ -0,0 +1,61 @@ +# Getting Started + +These instructions cover how to install $\textsf{R}$ in Windows. The tools required to build $\textsf{R}$ and $\textsf{R}$ packages in Windows are also discussed. + +## General instructions + +1. If you install the latest version or R-patched or R-devel, it will not over-write the previous installation(s) in your Windows machine. + +2. R uses a ‘major.minor.patchlevel’ version numbering scheme. Accordingly there are three main releases of $\textsf{R}$ available to install: + + * The official release (`r-release`), + + * The patched release (`r-patched`), and + + * The development (`r-devel`) release. + +The `r-devel` is the next minor or eventually major release development version of $\textsf{R}$. Mostly, bug fixes are introduced in `r-patched`, while `r-devel` is for introducing new features. + +## Installing $\textsf{R}$ + +1. The binary builds of $\textsf{R}$ for Windows can be downloaded and installed from [here](https://cran.r-project.org/bin/windows/base/). Along with the link to the latest stable release, this page also contains links to the binary builds of r-patched and r-devel. + +2. Click on the download links to download an executable installer. + +3. Select the language while installing, read the public license information, and select destination location to the start the installation. You will be prompted to select components at this stage: `User installation`, `32-bit User installation`, `64-bit User installation`, or `Custom installation`. The default option may be opted for the questions from this step onwards to complete the installation. + +## Building $\textsf{R}$ and $\textsf{R}$ packages + +### What tools you need to build $\textsf{R}$ from source on Windows? + +1. [RTools](https://github.com/r-windows/docs/blob/master/faq.md#what-is-rtools) is the toolchain bundle that you can use to build $\textsf{R}$ base and $\textsf{R}$ packages containing compiled code, on Windows. + +2. You also need a distribution of $\LaTeX$ installed for building $\textsf{R}$ and checking packages. The `MiKTeX` distribution of $\LaTeX$ that is used on CRAN can be downloaded from https://miktex.org. + +### How to setup `RTools`? + +1. The latest version of `RTools` can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure). + +2. Don't forget to add `RTools` to the path as documented on the download page. + +### How to build $\textsf{R}$? + +To build $\textsf{R}$ for Windows using `RTools` follow the instructions in this [README](https://github.com/r-windows/r-base#readme) file. There are two options available to build $\textsf{R}$. One is the quick development build and the other option is the full installer build. + +For development and testing, you need only the quick development build. The quick build avoids building the manuals, which are generally not needed for development and testing. + +However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh). For instance, `MikTeX` is to be installed in `C:/Program Files` and you have 64-bit $\textsf{R}$. If necessary, these defaults can be customised. The installation path of `MikTex` can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6). + +If you are a maintainer of the Windows CRAN releases then, the full installer build is available for building the complete installer as it appears on CRAN. It will build both the 32-bit and 64-bit $\textsf{R}$, the pdf manuals, and the installer program. You will use this to create the binary builds and not when building $\textsf{R}$ from the source yourself. + +## See also + +1. [CRAN official website](https://cran.r-project.org) + +2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html) + +3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) + +4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/) + +5. [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html) From 6f1381a26b2b9b064a9a989d0e0116d61f72d784 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sun, 11 Apr 2021 14:16:11 +0530 Subject: [PATCH 30/48] minor edits --- 02-getting_started.Rmd | 61 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 02-getting_started.Rmd diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd new file mode 100644 index 0000000..b898b27 --- /dev/null +++ b/02-getting_started.Rmd @@ -0,0 +1,61 @@ +# Getting Started + +These instructions cover how to install $\textsf{R}$ in Windows. The tools required to build $\textsf{R}$ and $\textsf{R}$ packages in Windows are also discussed. + +## General instructions + +1. If you install the latest version or R-patched or R-devel, it will not over-write the previous installation(s) in your Windows machine. + +2. R uses a ‘major.minor.patchlevel’ version numbering scheme. Accordingly there are three main releases of $\textsf{R}$ available to install: + + * The official release (`r-release`), + + * The patched release (`r-patched`), and + + * The development (`r-devel`) release. + +The `r-devel` is the next minor or eventually major release development version of $\textsf{R}$. Mostly, bug fixes are introduced in `r-patched`, while `r-devel` is for introducing new features. + +## Installing $\textsf{R}$ + +1. The binary builds of $\textsf{R}$ for Windows can be downloaded and installed from [here](https://cran.r-project.org/bin/windows/base/). Along with the link to the latest stable release, this page also contains links to the binary builds of r-patched and r-devel. + +2. Click on the download links to download an executable installer. + +3. Select the language while installing, read the public license information, and select destination location to the start the installation. You will be prompted to select components at this stage: `User installation`, `32-bit User installation`, `64-bit User installation`, or `Custom installation`. The default option may be opted for the questions from this step onwards to complete the installation. + +## Building $\textsf{R}$ and $\textsf{R}$ packages + +### What tools you need to build $\textsf{R}$ from source on Windows? + +1. [RTools](https://github.com/r-windows/docs/blob/master/faq.md#what-is-rtools) is the toolchain bundle that you can use to build $\textsf{R}$ base and $\textsf{R}$ packages containing compiled code, on Windows. + +2. You also need a distribution of $\LaTeX$ installed for building $\textsf{R}$ and checking packages. The `MiKTeX` distribution of $\LaTeX$ that is used on CRAN can be downloaded from https://miktex.org. + +### How to setup `RTools`? + +1. The latest version of `RTools` can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure). + +2. Don't forget to add `RTools` to the path as documented on the download page. + +### How to build $\textsf{R}$? + +To build $\textsf{R}$ for Windows using `RTools` follow the instructions in this [README](https://github.com/r-windows/r-base#readme) file. There are two options available to build $\textsf{R}$. One is the quick development build and the other option is the full installer build. + +For development and testing, you need only the quick development build. The quick build avoids building the manuals, which are generally not needed for development and testing. + +However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh). For instance, `MikTeX` is to be installed in `C:/Program Files` and you have 64-bit $\textsf{R}$. If necessary, these defaults can be customised. The installation path of `MikTex` can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6). + +If you are a maintainer of the Windows CRAN releases then, the full installer build is available for building the complete installer as it appears on CRAN. It will build both the 32-bit and 64-bit $\textsf{R}$, the pdf manuals, and the installer program. You will use this to create the binary builds and not when building $\textsf{R}$ from the source yourself. + +## See also + +1. [CRAN official website](https://cran.r-project.org) + +2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html) + +3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) + +4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/) + +5. [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html) From ddd991d1c37266363c797925868a1958a6a21e79 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sun, 11 Apr 2021 19:43:34 +0530 Subject: [PATCH 31/48] minor edits --- 11-bug_tracking.Rmd | 72 ++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 46 deletions(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 3728a96..054c655 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -2,10 +2,9 @@ ## What is a bug in $\textsf{R}$ ? -You may find a bug in $\textsf{R}$ if: +Following are some situations where you may find a bug in $\textsf{R}$: - -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: +1. The $\textsf{R}$ session terminates unexpectedly, or there is a segmentation fault, it might be a bug in $\textsf{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 *** @@ -17,22 +16,19 @@ You may find a bug in $\textsf{R}$ if: $\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 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 $\textsf{R}$ from the command line with the `--vanilla` option. - +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 condition might not be a bug? - +## 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. +2. Issues with [$\textit{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 $\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 someone to look over your code. This may perhaps not be a bug; instead, it might be an alternative way of writing the function. - +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 @@ -50,68 +46,48 @@ The sections that follow discuss where to check whether a bug is already reporte ## 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). - +1. [Report](#ReportBug) the bug (if it is not alreasy reported). -2. [Test](provide hyperlink to the section/chapter which discusses this) the bug. +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 either on BugZilla (link here) or on the GitHub mirror (link here). This would require engagement with $\textsf{R}$ Core team. +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 $\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). +1. In the [$\textsf{R}$-Core supported packages, their documentations, and/ or in the $\textsf{R}$ language](#RCorePkgBug). -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). +2. In [packages and/or their documentations which are not supported by the $\textsf{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 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. +Once you are confirmed that there is a bug, you need to submit a report so that it gets fixed. -2. Prior to reporting the issue, 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 found at either of these places, then please submit a new issue. +### Bug in the $\textsf{R}$-Core supported packages, their documentations, and/ or in the $\textsf{R}$ language {#RCorePkgBug} +1. Packages that are supported by the $\textsf{R}$-Core are labelled with `Maintainer: R Core Team `. One simple way to get the information from $\textsf{R}$ is by running the `maintainer("package_name")` command. -### 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 `. 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/). 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). - +2. The bug report for $\textsf{R}$-Core supported packages, their documentations, and/ or a bug report for the $\textsf{R}$ language itself 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} +### 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")`. +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")`. 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}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. Please ensure that your bug is not already reported or fixed before reporting it in any of the ways suggested above. -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 +## 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. +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. @@ -122,7 +98,11 @@ As humans, there might be differences of opinions from time to time. What needs 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. +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 $\textsf{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 .. links + +## use plain text R ## See also From fdcd5b2a323da7ea147dcbf64cbb048e12256271 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:05:54 +0530 Subject: [PATCH 32/48] Delete rdevguide.rds --- rdevguide.rds | Bin 303 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 rdevguide.rds diff --git a/rdevguide.rds b/rdevguide.rds deleted file mode 100644 index 9b9845937f33a7ebe573724d3b255bddef5239bc..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 303 zcmV+~0nq**iwFP!00000291*2PQx$^hP`e@3^WNb$~Zhj5v@StelIZXin}N@Zi&_w zsr5L#Ji~3p+N9gGn?$ky-~N*L^$Y-pFsfFU7dV+Og77&6aHf3XkaNNNfE8ojPj#;F z`yo>RBc~G|uX0TyLy~-`j9?35onk4JF8I)`cwSc&b=vYwbWT`gsI;UiY4|1$$(rJq z8V7zYRPQnL6C~1kB1)14q1ti}HYTRCv8vzn&0WNyt-ssR%s{i$PkyRnjDDgN#YZfp zSV)TAYqfES%OLRI)`_4(Mk_9U{0%(Ic@TeQx7q)!S3&3(_^I)$D$1tvc&1s;dywk3 z-^$=JhQ-ZgwjC1pf9jecS+b)ET<`d&HhaJCUs}o3eyKL)^>LRC>K}{$rvPOG008tJ BmHq$# From 1cc257f73e586f42f43741f6c269cf31db675c5d Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:08:50 +0530 Subject: [PATCH 33/48] use plain text R --- 11-bug_tracking.Rmd | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd index 054c655..450c91c 100644 --- a/11-bug_tracking.Rmd +++ b/11-bug_tracking.Rmd @@ -1,10 +1,10 @@ # Bug Tracking -## What is a bug in $\textsf{R}$ ? +## What is a bug in R? -Following are some situations where you may find a bug in $\textsf{R}$: +Following are some situations where you may find a bug in R: -1. The $\textsf{R}$ session terminates unexpectedly, or there is a segmentation fault, it might be a bug in $\textsf{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: +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 *** @@ -16,7 +16,7 @@ Following are some situations where you may find a bug in $\textsf{R}$: $\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. +1. Make sure whether the bug appears in a clean session of 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 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. @@ -26,7 +26,7 @@ When you are in doubt that there is a bug: 2. Issues with [$\textit{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 $\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. +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 some to look over your code. This may perhaps not be a bug, instead it might be an alternative way of writing the function. @@ -50,33 +50,33 @@ The sections that follow discuss where to check whether a bug is already reporte 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 $\textsf{R}$ Core team. +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 [$\textsf{R}$-Core supported packages, their documentations, and/ or in the $\textsf{R}$ language](#RCorePkgBug). +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 $\textsf{R}$-Core](#nonRCorePkgBug). +2. In [packages and/or their documentations which are not supported by the 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 $\textsf{R}$-Core supported packages, their documentations, and/ or in the $\textsf{R}$ language {#RCorePkgBug} +### Bug in the R-Core supported packages, their documentations, and/ or in the R language {#RCorePkgBug} -1. Packages that are supported by the $\textsf{R}$-Core are labelled with `Maintainer: R Core Team `. One simple way to get the information from $\textsf{R}$ is by running the `maintainer("package_name")` command. +1. Packages that are supported by the R-Core are labelled with `Maintainer: R Core Team `. One simple way to get the information from R is by running the `maintainer("package_name")` command. -2. The bug report for $\textsf{R}$-Core supported packages, their documentations, and/ or a bug report for the $\textsf{R}$ language itself 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). +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/) 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. +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)). 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 non $\textsf{R}$-Core supported packages and/or their documentations {#nonRCorePkgBug} +### Bug in the non R-Core supported packages and/or their documentations {#nonRCorePkgBug} -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")`. 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}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. Please ensure that your bug is not already reported or fixed before reporting it in any of the ways suggested above. +For packages that are not maintained by the 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")`. 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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. 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 @@ -98,12 +98,10 @@ As humans, there might be differences of opinions from time to time. What needs 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 $\textsf{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). +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 .. links -## use plain text R - ## See also 1. [Reporting a bug](https://www.r-project.org/bugs.html) From 5f46ab9f3014e8f28e0786a4d36d8a07d0508dce Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:18:00 +0530 Subject: [PATCH 34/48] change file name --- 03-bug_tracking_in_R.Rmd | 111 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 03-bug_tracking_in_R.Rmd diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd new file mode 100644 index 0000000..450c91c --- /dev/null +++ b/03-bug_tracking_in_R.Rmd @@ -0,0 +1,111 @@ +# Bug Tracking + +## What is a bug in R? + +Following are some situations where you may find a bug in R: + +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. + +$\textbf{Note}$: +When you are in doubt that there is a bug: + +1. Make sure whether the bug appears in a clean session of 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 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](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 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 alreasy 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 are confirmed that there is a bug, you need to submit a 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 `. 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/) 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 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 non R-Core supported packages and/or their documentations {#nonRCorePkgBug} + +For packages that are not maintained by the 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")`. 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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. 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. 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, 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 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 .. links + +## 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) From 21bed6c6ba4d41f6337f058ac2d84b97bc7f5b87 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:26:07 +0530 Subject: [PATCH 35/48] Delete 11-bug_tracking.Rmd --- 11-bug_tracking.Rmd | 111 -------------------------------------------- 1 file changed, 111 deletions(-) delete mode 100644 11-bug_tracking.Rmd diff --git a/11-bug_tracking.Rmd b/11-bug_tracking.Rmd deleted file mode 100644 index 450c91c..0000000 --- a/11-bug_tracking.Rmd +++ /dev/null @@ -1,111 +0,0 @@ -# Bug Tracking - -## What is a bug in R? - -Following are some situations where you may find a bug in R: - -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. - -$\textbf{Note}$: -When you are in doubt that there is a bug: - -1. Make sure whether the bug appears in a clean session of 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 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](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 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 alreasy 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 are confirmed that there is a bug, you need to submit a 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 `. 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/) 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 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 non R-Core supported packages and/or their documentations {#nonRCorePkgBug} - -For packages that are not maintained by the 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")`. 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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. 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. 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, 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 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 .. links - -## 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) From 49bd2d26090ab4d0cf28c2e422ee440911f3f247 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:29:18 +0530 Subject: [PATCH 36/48] change file name and use plain text R --- 04-reviewing_bugs_in_R.Rmd | 43 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 04-reviewing_bugs_in_R.Rmd diff --git a/04-reviewing_bugs_in_R.Rmd b/04-reviewing_bugs_in_R.Rmd new file mode 100644 index 0000000..b3d116c --- /dev/null +++ b/04-reviewing_bugs_in_R.Rmd @@ -0,0 +1,43 @@ +# Reviewing Bugs + +## How you can help to review bug reports? + +Once you are aware where bugs are reported in R, a great way to contribute is to help reviewing the 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. + +Note: + +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 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. Clearly explains the bug so that it can be reproduced. + +2. Includes the version of R, the machine architecture, and the operating system platform on which the bug occurred. + +These are the relevant details that should be a part of a good bug report. You can help with these things once you have 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. 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. + +This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. + +## How to find a bug report or an issue that you can help with? + +1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. + +2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. + +## share that you can report on bugreports for review on r-devel slack or on the GH mirror + +## Share examples where people have acted as reviewers for the bug reports + +## 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/) From 32f03a68ad90ae4674262cfce49883e284a05b89 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:31:46 +0530 Subject: [PATCH 37/48] Delete rdevguide.rds --- rdevguide.rds | Bin 303 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 rdevguide.rds diff --git a/rdevguide.rds b/rdevguide.rds deleted file mode 100644 index 9b9845937f33a7ebe573724d3b255bddef5239bc..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 303 zcmV+~0nq**iwFP!00000291*2PQx$^hP`e@3^WNb$~Zhj5v@StelIZXin}N@Zi&_w zsr5L#Ji~3p+N9gGn?$ky-~N*L^$Y-pFsfFU7dV+Og77&6aHf3XkaNNNfE8ojPj#;F z`yo>RBc~G|uX0TyLy~-`j9?35onk4JF8I)`cwSc&b=vYwbWT`gsI;UiY4|1$$(rJq z8V7zYRPQnL6C~1kB1)14q1ti}HYTRCv8vzn&0WNyt-ssR%s{i$PkyRnjDDgN#YZfp zSV)TAYqfES%OLRI)`_4(Mk_9U{0%(Ic@TeQx7q)!S3&3(_^I)$D$1tvc&1s;dywk3 z-^$=JhQ-ZgwjC1pf9jecS+b)ET<`d&HhaJCUs}o3eyKL)^>LRC>K}{$rvPOG008tJ BmHq$# From e7bed0d4c5b29e9254f761f0b54f162a182803cf Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 12:32:12 +0530 Subject: [PATCH 38/48] Delete 12-reviewing_bugs.Rmd --- 12-reviewing_bugs.Rmd | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 12-reviewing_bugs.Rmd diff --git a/12-reviewing_bugs.Rmd b/12-reviewing_bugs.Rmd deleted file mode 100644 index 035a89f..0000000 --- a/12-reviewing_bugs.Rmd +++ /dev/null @@ -1,39 +0,0 @@ -# Reviewing Bugs - -## How you can help to review bug reports? - -Once you are aware where bugs are reported in $\textsf{R}$, a great way to contribute is to help reviewing the bug reports. - -Around the clock, new bug reports are being submitted on Bugzilla or the bug trackers (for instance, GitHub issues) of $\textsf{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. - -Note: - -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 login. Briefly explain why you want a Bugzilla account and a volunteer will add you to $\textsf{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. Clearly explains the bug so that it can be reproduced. - -2. Includes the version of $\textsf{R}$, the machine architecture, and the operating system platform on which the bug occurred. - -These are the relevant details that should be a part of a good bug report. You can help with these things once you have $\textsf{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. Check whether the bug occurs on a different binary build of $\textsf{R}$. It is helpful to know whether the bug is affecting: `r-patched`, `r-devel`, or `r-release` binary builds of $\textsf{R}$. - -3. Writing a unit test: If the bug report lacks a unit test that should be a part of $\textsf{R}$'s test suite, then you can help with providing it. - -This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. - -## How to find a bug report or an issue that you can help with? - -1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. - -2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. - -## 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/) From 7558c3bac430ac3a49e91ecd9070c64b52e3c7ce Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 14:10:32 +0530 Subject: [PATCH 39/48] examples of bug reports added --- 03-bug_tracking_in_R.Rmd | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 450c91c..2ef5ab4 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -2,7 +2,7 @@ ## What is a bug in R? -Following are some situations where you may find 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: @@ -16,11 +16,11 @@ Following are some situations where you may find a bug in R: $\textbf{Note}$: When you are in doubt that there is a bug: -1. Make sure whether the bug appears in a clean session of 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 R from the command line with the `--vanilla` option. +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. -## What may not be a bug? +## 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. @@ -28,7 +28,7 @@ When you are in doubt that there is a bug: 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 some to look over your code. This may perhaps not be a bug, instead it might be an alternative way of writing the function. +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 @@ -46,7 +46,7 @@ The sections that follow discuss where to check whether a bug is already reporte ## Levels of contributing to bug / What do you do when you find a bug? -1. [Report](#ReportBug) the bug (if it is not alreasy reported). +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. @@ -62,21 +62,21 @@ You may find a bug in: ## 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. +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 `. 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/) or as an issue to the [GitHub Mirror of R svn server](https://github.com/r-devel/r-svn/issues). +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)). 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. +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 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")`. 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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. Please ensure that your bug is not already reported or fixed before reporting it in any of the ways suggested above. +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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{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 @@ -100,7 +100,13 @@ If you take some time, then on reflection, the resolution steps may seem more re 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 .. links +## Examples of Bug reports submitted on Bugzilla + +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 via R-devel mailing list. (More information about the R-devel mailing list can be found [here](https://stat.ethz.ch/mailman/listinfo/r-devel)). ## See also From 31c56bc6eb5c5eb0db75cf4b782a7ff1c1ca6de0 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 15:08:34 +0530 Subject: [PATCH 40/48] markdown syntax for bold/italic --- 03-bug_tracking_in_R.Rmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 2ef5ab4..9abbea3 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -13,7 +13,7 @@ You may find a bug in R if: 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}$: +**Note**: When you are in doubt that there is a bug: 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. @@ -24,7 +24,7 @@ When you are in doubt that there is 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](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. +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. From fef488b359f15829c772aee82ce5295a99cc8e72 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 17:00:29 +0530 Subject: [PATCH 41/48] Delete 04-reviewing_bugs_in_R.Rmd --- 04-reviewing_bugs_in_R.Rmd | 43 -------------------------------------- 1 file changed, 43 deletions(-) delete mode 100644 04-reviewing_bugs_in_R.Rmd diff --git a/04-reviewing_bugs_in_R.Rmd b/04-reviewing_bugs_in_R.Rmd deleted file mode 100644 index b3d116c..0000000 --- a/04-reviewing_bugs_in_R.Rmd +++ /dev/null @@ -1,43 +0,0 @@ -# Reviewing Bugs - -## How you can help to review bug reports? - -Once you are aware where bugs are reported in R, a great way to contribute is to help reviewing the 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. - -Note: - -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 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. Clearly explains the bug so that it can be reproduced. - -2. Includes the version of R, the machine architecture, and the operating system platform on which the bug occurred. - -These are the relevant details that should be a part of a good bug report. You can help with these things once you have 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. 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. - -This is all helpful as it allows the Core developers and/ or maintainers to classify a bug report properly, so that it can be handled in a timely fashion. - -## How to find a bug report or an issue that you can help with? - -1. You may find old bug reports or issues that can be closed, either because they are no longer valid or they have a patch that is ready to be committed, but no one has had the time to do so. - -2. You might also want to search for issues in topics which you have a working knowledge. When on Bugzilla you can use the advanced search for specific topics. Bug reports are by default public on Bugzilla (unless the defaults are changed to avoid security vulnerability), so you can select from them. - -## share that you can report on bugreports for review on r-devel slack or on the GH mirror - -## Share examples where people have acted as reviewers for the bug reports - -## 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/) From e07d34c99a4e19d13e03d245a29d9395b2aff958 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 17:02:39 +0530 Subject: [PATCH 42/48] Add files via upload --- 04-reviewing_bugs_in_R.Rmd | 49 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 04-reviewing_bugs_in_R.Rmd diff --git a/04-reviewing_bugs_in_R.Rmd b/04-reviewing_bugs_in_R.Rmd new file mode 100644 index 0000000..35e6ede --- /dev/null +++ b/04-reviewing_bugs_in_R.Rmd @@ -0,0 +1,49 @@ +# 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). + +## share that you can report on bugreports for review on r-devel slack or on the GH mirror + +## 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/) From 93599517b9231c2135276cfd6bb7c106f7e38de8 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 18:59:13 +0530 Subject: [PATCH 43/48] avoid markup for names --- 02-getting_started.Rmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-getting_started.Rmd b/02-getting_started.Rmd index 36d7f78..50554a4 100644 --- a/02-getting_started.Rmd +++ b/02-getting_started.Rmd @@ -30,7 +30,7 @@ The `r-devel` is the next minor or eventually major release development version 1. [RTools](https://github.com/r-windows/docs/blob/master/faq.md#what-is-rtools) is the toolchain bundle that you can use to build R base and R packages containing compiled code, on Windows. -2. You also need a distribution of $\LaTeX$ installed for building R and checking packages. The `MiKTeX` distribution of $\LaTeX$ that is used on CRAN can be downloaded from https://miktex.org. +2. You also need a distribution of $\LaTeX$ installed for building R and checking packages. The MiKTeX distribution of LaTeX that is used on CRAN can be downloaded from https://miktex.org. ### How to setup `RTools`? @@ -44,7 +44,7 @@ To build R for Windows using `RTools` follow the instructions in this [README](h For development and testing, you need only the quick development build. The quick build avoids building the manuals, which are generally not needed for development and testing. -However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh). For instance, `MikTeX` is to be installed in `C:/Program Files` and you have 64-bit R. If necessary, these defaults can be customised. The installation path of `MikTex` can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6). +However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh). For instance, MikTeX is to be installed in `C:/Program Files` and you have 64-bit R. If necessary, these defaults can be customised. The installation path of MikTex can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6). If you are a maintainer of the Windows CRAN releases then, the full installer build is available for building the complete installer as it appears on CRAN. It will build both the 32-bit and 64-bit R, the pdf manuals, and the installer program. You will use this to create the binary builds and not when building R from the source yourself. From d9b05bbbb12873def15218713dcf7e9ca15161da Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Mon, 12 Apr 2021 19:02:08 +0530 Subject: [PATCH 44/48] avoid markup for names --- 03-bug_tracking_in_R.Rmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 9abbea3..9af8c0e 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -76,11 +76,11 @@ Once you confirm a bug exists, you need to submit a bug report so that it gets f ### 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 $\textbf{RStudio}$, by default. However, if you use `utils::bug.report(package = "package_name")` then it works on $\textbf{RStudio}$ as well. Please ensure that the bug is not already reported or fixed before reporting it in any of the ways suggested above. +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. +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. From bde4fffca4c7b61c2a9aaa81549a57acbebfcd97 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 13 Apr 2021 06:58:40 +0530 Subject: [PATCH 45/48] remove comment --- 04-reviewing_bugs_in_R.Rmd | 2 -- 1 file changed, 2 deletions(-) diff --git a/04-reviewing_bugs_in_R.Rmd b/04-reviewing_bugs_in_R.Rmd index 35e6ede..0cb7ce3 100644 --- a/04-reviewing_bugs_in_R.Rmd +++ b/04-reviewing_bugs_in_R.Rmd @@ -34,8 +34,6 @@ These helpful tasks allow the Core developers and/ or maintainers to classify a 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). -## share that you can report on bugreports for review on r-devel slack or on the GH mirror - ## 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. From 93f0d31078a10b3e68a1b320b16f037bfef925a1 Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Tue, 13 Apr 2021 07:09:43 +0530 Subject: [PATCH 46/48] wording changes --- 03-bug_tracking_in_R.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 9af8c0e..6131dd4 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -94,7 +94,7 @@ Once you have successfully reported a bug, you will likely receive an update eac ## 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. +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. From 208d978d8111c5a405768e4f082e669a245ae9f3 Mon Sep 17 00:00:00 2001 From: Toby Dylan Hocking Date: Fri, 30 Apr 2021 07:31:22 -0700 Subject: [PATCH 47/48] Update 03-bug_tracking_in_R.Rmd --- 03-bug_tracking_in_R.Rmd | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 6131dd4..2934dc9 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -14,12 +14,16 @@ You may find a bug in R if: 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: +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. From 63efd53f5c9e119a2003de4c6a8a6bf4a6fc033d Mon Sep 17 00:00:00 2001 From: Saranjeet Kaur Date: Sat, 1 May 2021 02:01:02 +0530 Subject: [PATCH 48/48] more egs of bug reports submitted & fixed/merged --- 03-bug_tracking_in_R.Rmd | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/03-bug_tracking_in_R.Rmd b/03-bug_tracking_in_R.Rmd index 2934dc9..5011f1b 100644 --- a/03-bug_tracking_in_R.Rmd +++ b/03-bug_tracking_in_R.Rmd @@ -104,13 +104,17 @@ If you take some time, then on reflection, the resolution steps may seem more re 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 +## 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 via R-devel mailing list. (More information about the R-devel mailing list can be found [here](https://stat.ethz.ch/mailman/listinfo/r-devel)). +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