-
Notifications
You must be signed in to change notification settings - Fork 21
/
rdevguide.tex
2093 lines (1652 loc) · 110 KB
/
rdevguide.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{book}
\usepackage{amsmath,amssymb}
\usepackage{iftex}
\ifPDFTeX
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
\usepackage{unicode-math} % this also loads fontspec
\defaultfontfeatures{Scale=MatchLowercase}
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
\usepackage{lmodern}
\ifPDFTeX\else
% xetex/luatex font selection
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
\usepackage[]{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
\KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\usepackage{framed}
\definecolor{shadecolor}{RGB}{248,248,248}
\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\BuiltInTok}[1]{#1}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\ImportTok}[1]{#1}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\usepackage{longtable,booktabs,array}
\usepackage{calc} % for calculating minipage widths
% Correct order of tables after \paragraph or \subparagraph
\usepackage{etoolbox}
\makeatletter
\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
\makeatother
% Allow footnotes in longtable head/foot
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
\makesavenoteenv{longtable}
\usepackage{graphicx}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
% Set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
\usepackage{booktabs}
\ifLuaTeX
\usepackage{selnolig} % disable illegal ligatures
\fi
\usepackage[]{natbib}
\bibliographystyle{apalike}
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\urlstyle{same}
\hypersetup{
pdftitle={R Development Guide},
pdfauthor={R Contribution Working Group},
hidelinks,
pdfcreator={LaTeX via pandoc}}
\title{R Development Guide}
\author{R Contribution Working Group}
\date{2023-08-30}
\begin{document}
\maketitle
{
\setcounter{tocdepth}{1}
\tableofcontents
}
\hypertarget{section}{%
\chapter*{}\label{section}}
\addcontentsline{toc}{chapter}{}
\begin{figure}
\centering
\includegraphics[width=5.20833in,height=4.16667in]{img/Rlogo.png}
\caption{R Logo}
\end{figure}
\hypertarget{acknowledgement}{%
\chapter*{Acknowledgement}\label{acknowledgement}}
\addcontentsline{toc}{chapter}{Acknowledgement}
This guide draws on documentation and articles written by the R Core Team. The first version of the guide was heavily influenced by the \href{https://devguide.python.org/}{Python Developer's Guide}.
Initial chapters of the guide were developed by Saranjeet Kaur Bhogal, in a project funded by the R Foundation, mentored by Heather Turner and Michael Lawrence. This initial version was upgraded in a \href{https://github.com/rstats-gsod/gsod2022/wiki/GSOD-2022-Proposal}{Google Season of Docs 2022} project with Saranjeet Kaur Bhogal and Lluís Revilla Sancho working as technical writers managed by Nicolas Bennett and overseen by a \href{https://github.com/rstats-gsod/gsod2022/wiki/GSOD-2022-Proposal\#steering-committee}{Steering Committee} including representatives from R Core and the wider R community.
This guide has benefited and continues to benefit from varied contributions by several \href{https://github.com/r-devel/rdevguide\#contributors-}{contributors}.
\href{https://creativecommons.org/licenses/by/4.0/}{\includegraphics{img/ccby.png}}
This project is licensed under a \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International (CC BY 4.0)}. Some pages may contain materials that are subject to copyright, in which case you will see the copyright notice.
\hypertarget{introduction}{%
\chapter{Introduction}\label{introduction}}
This guide is a comprehensive resource for contributing to base R\footnote{The \href{https://cran.r-project.org/doc/FAQ/R-FAQ.html\#Add_002don-packages-in-R}{set of packages} in the base R distribution that are maintained by the R Core Team.} -- for both new and experienced contributors. It is maintained by the \href{/working-group}{R Contribution Working Group}. We welcome your contributions to base R!
\hypertarget{overview-of-different-ways-of-contributing-to-the-base-r-project}{%
\section{Overview of different ways of contributing to the base R Project}\label{overview-of-different-ways-of-contributing-to-the-base-r-project}}
Contributions to base R are possible in a number of different ways. Some of them are listed below:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
Contributing to bug fixing: Refer \protect\hyperlink{BugTrack}{Bug Tracking} and \protect\hyperlink{ReviewBugs}{Reviewing Bugs}.
\item
Contributing to translations: Refer \protect\hyperlink{}{Translations}.
\item
Testing R before release: Refer \protect\hyperlink{TestRVer}{Testing Pre-release R Versions}.
\end{enumerate}
\hypertarget{quick-start-to-the-guide}{%
\section{Quick start to the guide}\label{quick-start-to-the-guide}}
The guide is intended as a comprehensive resource for contributing to base R. The following chapter outline provides an overview with links to sections for getting started with contributing.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
The \protect\hyperlink{GetStart}{Getting Started} covers the instructions on how to install R on the major operating systems (Windows, Linux and macOS), as well as the tools required to build R and R packages from source.
\end{enumerate}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{1}
\item
The \protect\hyperlink{BugTrack}{Bug Tracking} and the \protect\hyperlink{ReviewBugs}{Reviewing Bugs} chapters discuss how to find bugs in R and how to review bug reports that are submitted to Bugzilla.
\item
The \protect\hyperlink{FindSource}{Finding the Source} chapter provides an overview of the R codebase and helps with finding source code of base functions written in R and/or C.
\item
The \protect\hyperlink{FixBug}{Lifecycle of a Patch} chapter discusses how to create a patch to propose a bug fix.
\item
The \protect\hyperlink{Doc}{Documenting R} chapter describes the format and style guide for help files in R, how to report and review issues in the existing documentation and how to propose changes.
\item
How to test pre-release versions of R is discussed in the chapter on \protect\hyperlink{TestRVer}{Testing Pre-release R Versions}.
\item
The \protect\hyperlink{CoreDev}{R Core Developers} chapter contains a list of the former and current members of the R Core team who have write access to the R source.
\item
For more information on how to engage with to community and ask for help, refer to the \protect\hyperlink{WhereToGetHelp}{Where to Get Help} chapter.
\item
To keep up with the developments in R refer to some of the resources available in the \protect\hyperlink{News}{News and Announcements}
\item
Resources and tools that may be relevant for R developers are available in the \protect\hyperlink{DevTools}{Developer Tools} chapter.
\end{enumerate}
\hypertarget{how-to-contribute-to-this-guide}{%
\section{How to contribute to this guide itself?}\label{how-to-contribute-to-this-guide}}
This guide is built using bookdown which makes editing it easier, provided you have a GitHub account (sign-up at \href{https://github.com/}{github.com}). After you log-in to GitHub, click on the `Edit' icon highlighted with a red ellipse in the image below. This will take you to an editable version of the the source R Markdown file that generated the page you are on:
\begin{figure}
\centering
\includegraphics{img/edit_icon.png}
\caption{Screenshot of the toolbar in the HTML version of the guide, with the Edit button (pencil and paper icon) circled in red.}
\end{figure}
Use the \href{https://github.com/r-devel/rdevguide/issues}{issue tracker} to raise an issue about the guide's content or to make a feature request.
Maintainers and contributors are requested to follow this project's \href{https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md}{code of conduct}.
\hypertarget{GetStart}{%
\chapter{R Patched and Development Versions}\label{GetStart}}
These instructions cover how to install R from source or from binaries.
Contributors will typically need to work with the patched or development versions of R.
This chapter describes where the source code for these versions can be found and how to install these versions from the source or the binary builds (where available).
The tools required to build R and R packages are also discussed.
For the most up to date and complete instructions you can check the \href{https://cran.r-project.org/doc/manuals/r-devel/R-admin.html}{R installation and administration manual} .
\hypertarget{the-r-source-code}{%
\section{The R source code}\label{the-r-source-code}}
R uses \href{https://subversion.apache.org/}{svn} as a version control tool hosted at \url{https://svn.r-project.org/R/} and uses a `major.minor.patchlevel' version numbering scheme\footnote{Also known as \href{https://en.wikipedia.org/wiki/Software_versioning\#Semantic_versioning}{semantic versioning}}.
There are three releases of R available to install:
\begin{itemize}
\item
The latest official release (\texttt{r-release}), either major version x.0.0 or minor version x.y.0, for example: 3.0.0 or 3.2.0
\item
The patched release (\texttt{r-patched}), for example 3.0.1 or 3.2.1 and
\item
The development release (\texttt{r-devel}) : continually developed version moving from r-release to next major/minor version (x + 1).0.0 or x.(y + 1).0 a few weeks before release (at the start of the ``GRAND FEATURE FREEZE'').
\end{itemize}
The source code of released versions of R can be found at \href{https://svn.r-project.org/R/tags/}{R/tags}, the patched versions are at \href{https://svn.r-project.org/R/branches/}{R/branch}.
The \texttt{r-devel} at \href{https://svn.r-project.org/R/trunk}{R/trunk} is the next minor or eventual major release development version of R.
Bug fixes and new features are introduced in \texttt{r-devel} first.
If the change meets the \href{https://developer.r-project.org/devel-guidelines.txt}{development guidelines} R Core will also make the change in \texttt{r-patched}.
\hypertarget{prerequisites}{%
\section{Prerequisites}\label{prerequisites}}
To install from the source code you will need the source code and the dependencies of R.
If you need to install svn you can use your distribution's package manager to install it.
\hypertarget{ubuntu}{%
\subsection{Ubuntu}\label{ubuntu}}
In Ubuntu you can use this command to find all the dependencies of R:
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{apt{-}rdepends} \AttributeTok{{-}{-}build{-}depends} \AttributeTok{{-}{-}follow}\OperatorTok{=}\NormalTok{DEPENDS r{-}base{-}dev }\KeywordTok{|} \FunctionTok{grep} \StringTok{" B"} \KeywordTok{|} \FunctionTok{sed} \AttributeTok{{-}e} \StringTok{"s/ Build{-}Depends: //"}
\end{Highlighting}
\end{Shaded}
It might require installation of apt-rdepends which can be done from default repositories via \texttt{sudo\ apt-get\ install\ apt-rdepends}.
To install all the R dependencies you can use:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{sudo}\NormalTok{ apt{-}get build{-}dep r{-}base{-}dev}
\end{Highlighting}
\end{Shaded}
\hypertarget{fedora}{%
\subsection{Fedora}\label{fedora}}
In Fedora you can use this command to find all the dependencies of R:
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{dnf}\NormalTok{ rq }\AttributeTok{{-}q} \AttributeTok{{-}{-}repo}\OperatorTok{=}\NormalTok{fedora{-}source }\AttributeTok{{-}{-}requires}\NormalTok{ R }
\end{Highlighting}
\end{Shaded}
You will also need the rsync package to download the recommended packages.
To install them you can use:
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{dnf}\NormalTok{ install }\StringTok{\textquotesingle{}dnf{-}command(builddep)\textquotesingle{}}
\ExtensionTok{dnf}\NormalTok{ install rsync}
\ExtensionTok{dnf}\NormalTok{ builddep R}
\end{Highlighting}
\end{Shaded}
\hypertarget{building-r}{%
\section{Building R}\label{building-r}}
\hypertarget{linux}{%
\subsection{Linux}\label{linux}}
Here are the basic steps intended as a checklist.
For complete instructions please see the section in \href{https://cran.r-project.org/doc/manuals/r-devel/R-admin.html\#Installing-R-under-Unix_002dalikes}{R-admin}.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{-1}
\item
Retrieve R source code via into \texttt{TOP\_SRCDIR}, note that we retrieve the \texttt{r-devel} source code:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{TOP\_SRCDIR}\OperatorTok{=}\StringTok{"}\VariableTok{$HOME}\StringTok{/Downloads/R"}
\FunctionTok{svn}\NormalTok{ checkout https://svn.r{-}project.org/R/trunk/ }\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{"}
\end{Highlighting}
\end{Shaded}
\item
Download the latest recommended packages\footnote{Recommended packages are not in the subversion repository.}:
\begin{Shaded}
\begin{Highlighting}[]
\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{/tools/rsync{-}recommended"}
\end{Highlighting}
\end{Shaded}
\item
Create the build directory in the \texttt{BUILDDIR}:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{BUILDDIR}\OperatorTok{=}\StringTok{"}\VariableTok{$HOME}\StringTok{/bin/R"}
\FunctionTok{mkdir} \AttributeTok{{-}p} \StringTok{"}\VariableTok{$BUILDDIR}\StringTok{"}
\BuiltInTok{cd} \StringTok{"}\VariableTok{$BUILDDIR}\StringTok{"}
\end{Highlighting}
\end{Shaded}
\item
Configure the R installation (with \texttt{-\/-enable-R-shlib} so that RStudio IDE can use it):
\begin{Shaded}
\begin{Highlighting}[]
\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{/configure"} \AttributeTok{{-}{-}enable{-}R{-}shlib}
\end{Highlighting}
\end{Shaded}
\item
Build R :
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}
\end{Highlighting}
\end{Shaded}
\item
Check that R works as expected:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}\NormalTok{ check}
\end{Highlighting}
\end{Shaded}
There are other checks you can run:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}\NormalTok{ check{-}devel}
\FunctionTok{make}\NormalTok{ check{-}recommended}
\end{Highlighting}
\end{Shaded}
\end{enumerate}
If we don't want to build R in a different directory than the source code we can simply use:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{cd} \StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{"}
\FunctionTok{svn}\NormalTok{ update}
\ExtensionTok{tools/rsync{-}recommended}
\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{/configure"} \AttributeTok{{-}{-}enable{-}R{-}shlib}
\FunctionTok{make}
\FunctionTok{make}\NormalTok{ check}
\end{Highlighting}
\end{Shaded}
Once you successfully built R from source you can modify the R source code to fix an issue: Prepare a patch (See \href{https://www.r-project.org/bugs.html\#how-to-submit-patches}{this guide}) and after checking that R works as intended (\texttt{make\ check-devel}) submit the patch for consideration by R Core.
(See the \protect\hyperlink{FixBug}{lifecycle of a patch} chapter).
To use the \texttt{r-devel} version in RStudio, you can do the following:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{RSTUDIO\_WHICH\_R}\OperatorTok{=}\StringTok{"}\VariableTok{$BUILDDIR}\StringTok{/bin/R"}
\BuiltInTok{cd} \StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{"}
\ExtensionTok{rstudio}
\end{Highlighting}
\end{Shaded}
\hypertarget{windows}{%
\subsection{Windows}\label{windows}}
\hypertarget{binaries}{%
\subsubsection{Binaries}\label{binaries}}
The binary builds of R for Windows can be downloaded and installed from \href{https://cran.r-project.org/bin/windows/base/}{here}.
Along with the link to the latest stable release, this page also contains links to the binary builds of \texttt{r-patched} and \texttt{r-devel}.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Click on the download links to download an executable installer.
\item
Select the language while installing, read the GNU general public license information, and select the destination location to start the installation.
You will be prompted to select components at this stage: \texttt{User\ installation}, \texttt{64-bit\ User\ installation}, or \texttt{Custom\ installation}.
The default option may be chosen for the questions from this step onwards to complete the installation.
\end{enumerate}
Daily binaries for \texttt{r-devel} are made available for \href{https://cran.r-project.org/bin/windows/base/rdevel.html}{download and installation}.
\hypertarget{windowsSource}{%
\subsubsection{From source}\label{windowsSource}}
Before installing R from source, some additional programs are needed, as per the \href{https://cran.r-project.org/bin/windows/base/howto-R-4.2.html}{latest documentation}:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://cran.r-project.org/bin/windows/Rtools/}{Rtools} is the suggested toolchain bundle for building R base and R packages containing compiled code on Windows.
The latest \href{https://cran.r-project.org/bin/windows/Rtools/rtools43/rtools.html}{version of Rtools} can be installed using the \href{https://cran.r-project.org/bin/windows/Rtools/rtools43/files/}{Rtools installer rtools43-XXXX-XXX.exe}.
\item
A LaTeX compiler is needed to install and build R, check packages and build manuals.
On CRAN, MiKTeX is used, which can be downloaded from \url{https://miktex.org}.
Once installed open MiKTeX via the Windows start menu.
It might ask to check for updates and more importantly, to make it available in PATH. You can accept both.
\item
Open the Rtools42 terminal to update and install subversion:
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{pacman} \AttributeTok{{-}Syuu}
\ExtensionTok{pacman} \AttributeTok{{-}Sy}\NormalTok{ wget subversion}
\end{Highlighting}
\end{Shaded}
\item
Retrieve the latest source code via subversion:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{TOP\_SRCDIR}\OperatorTok{=}\StringTok{"}\VariableTok{$HOME}\StringTok{/Downloads/R"}
\FunctionTok{svn}\NormalTok{ checkout https://svn.r{-}project.org/R/trunk/ }\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{"}
\end{Highlighting}
\end{Shaded}
If you already have the repository available you can update as:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{cd} \VariableTok{$TOP\_SRCDIR}
\FunctionTok{svn}\NormalTok{ update}
\end{Highlighting}
\end{Shaded}
You can also use a SVN client such as TortoiseSVN (\url{https://tortoisesvn.net/}, command line tool, and Windows Explorer integration) or SlikSVN (\url{https://sliksvn.com/download/}, just the command line tool) so that it can be also found by other tools.
\item
Download the latest tcl/tk and unzip it in \texttt{\$TOP\_SRCDIR}:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{cd} \StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{"}
\FunctionTok{wget} \AttributeTok{{-}np} \AttributeTok{{-}nd} \AttributeTok{{-}r} \AttributeTok{{-}l1} \AttributeTok{{-}A} \StringTok{\textquotesingle{}tcltk{-}*.zip\textquotesingle{}}\NormalTok{ https://cran.r{-}project.org/bin/windows/Rtools/rtools43/files/}
\FunctionTok{unzip} \StringTok{"tcltk{-}*.zip"}
\end{Highlighting}
\end{Shaded}
\item
Add gcc, MiKTeX and tar to the PATH and set one tar option:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{PATH}\OperatorTok{=}\StringTok{"/x86\_64{-}w64{-}mingw32.static.posix/bin:}\VariableTok{$PATH}\StringTok{"}
\BuiltInTok{export} \VariableTok{PATH}\OperatorTok{=}\StringTok{"/c/Program Files/MiKTeX/miktex/bin/x64:}\VariableTok{$PATH}\StringTok{"}
\BuiltInTok{export} \VariableTok{TAR}\OperatorTok{=}\StringTok{"/usr/bin/tar"}
\BuiltInTok{export} \VariableTok{TAR\_OPTIONS}\OperatorTok{=}\StringTok{"{-}{-}force{-}local"}
\end{Highlighting}
\end{Shaded}
If MiKTeX was installed just for your user you might need to run:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{export} \VariableTok{PATH}\OperatorTok{=}\StringTok{"/c/Users/}\VariableTok{$USER}\StringTok{/AppData/Local/Programs/MiKTeX/miktex/bin/x64:}\VariableTok{$PATH}\StringTok{"}
\end{Highlighting}
\end{Shaded}
\item
Check that all the programs can be found:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{which}\NormalTok{ make gcc pdflatex tar}
\end{Highlighting}
\end{Shaded}
If there is any error you'll need to find where the program is installed and add the corresponding path.
\item
Download the latest recommended packages\footnote{Recommended packages are not in the subversion repository.}:
\begin{Shaded}
\begin{Highlighting}[]
\BuiltInTok{cd} \StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{/src/gnuwin32/"}
\StringTok{"}\VariableTok{$TOP\_SRCDIR}\StringTok{/tools/rsync{-}recommended"}
\end{Highlighting}
\end{Shaded}
\item
Build R and the recommended packages:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}\NormalTok{ all recommended}
\end{Highlighting}
\end{Shaded}
The recently compiled version of R will be at \texttt{\$TOP\_SRCDIR/bin/}.
In RStudio you can select that folder and restart it to use the \texttt{r-devel} version.
\item
Check that R works as expected:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}\NormalTok{ check}
\end{Highlighting}
\end{Shaded}
There are other checks you can run for testing the successful installation of the recommended packages:
\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{make}\NormalTok{ check{-}devel}
\FunctionTok{make}\NormalTok{ check{-}recommended}
\end{Highlighting}
\end{Shaded}
\end{enumerate}
\hypertarget{macos}{%
\subsection{macOS}\label{macos}}
This section will be added after the official \href{https://cran.r-project.org/doc/manuals/r-devel/R-admin.html\#macOS}{installation instructions for macOS in the R installation and administration manual} have been updated for R 4.3.0.
\hypertarget{see-also}{%
\section{See also}\label{see-also}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://cran.r-project.org}{CRAN official website}
\item
\href{https://cran.r-project.org/doc/manuals/r-patched/R-admin.html}{R installation and administration manual}
\item
\href{https://mac.r-project.org/}{R for macOS}
\item
\href{https://mac.r-project.org/tools/}{Tools for R in macOS}
\item
\href{https://mac.r-project.org/src/}{R for requirements in macOS}
\item
\href{https://cran.r-project.org/bin/windows/base/rw-FAQ.html}{R for Windows FAQ}
\item
\href{https://cran.r-project.org/bin/windows/Rtools/}{RTools toolchains for Windows}
\item
\href{https://cran.r-project.org/doc/FAQ/R-FAQ.html}{R FAQ}
\end{enumerate}
\hypertarget{IssueTrack}{%
\chapter{Issue Tracking}\label{IssueTrack}}
Base R uses \href{https://bugs.r-project.org/}{Bugzilla} for issue tracking and reporting bugs.
\hypertarget{how-to-contribute-to-issue-tracking}{%
\section{How to contribute to issue tracking?}\label{how-to-contribute-to-issue-tracking}}
Contributors can support issue tracking in R by
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://contributor.r-project.org/rdevguide/ReportBugs.html}{Reporting bugs} or making feature requests (bug reports filed under the ``Wishlist'' component in Bugzilla),
\item
\href{https://contributor.r-project.org/rdevguide/ReviewBugs.html}{Reviewing bug reports} to help close reports where no fix is needed or to help narrow down the problem and identify what needs to be fixed, or
\item
\href{https://contributor.r-project.org/rdevguide/FixBug.html\#FixBug}{Proposing changes} to code or documentation that will close an issue.
\end{enumerate}
\hypertarget{bugzilla-account}{%
\section{How to get a Bugzilla account?}\label{bugzilla-account}}
Anyone can browse the bug reports on Bugzilla, but you will need an account to file a bug report, to comment on an existing bug report, or to submit a proposed fix in the form of patch file.
To get a Bugzilla account send an e-mail to \texttt{[email protected]} 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. After having successfully logged in to Bugzilla, you are good to go.
\hypertarget{Bugzilla}{%
\subsection{Navigating Bugzilla}\label{Bugzilla}}
An image of the existing home page of Bugzilla is shared below:
\begin{figure}
\centering
\includegraphics{img/bugzilla.png}
\caption{Screenshot of the existing home page of Bugzilla.}
\end{figure}
On the home page of Bugzilla, there are various buttons and links. There are four square buttons called as:
\begin{figure}
\centering
\includegraphics{img/squarebuttons.png}
\caption{Screenshot of the four square buttons on the home page of Bugzilla.}
\end{figure}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://bugs.r-project.org/enter_bug.cgi}{File a bug}: You will have to log in to Bugzilla to file a bug using this button
\item
\href{https://bugs.r-project.org/query.cgi}{Search}: When you click this button you will get a page with `Simple Search' and `Advanced Search' options. Either of the search options could be used depending on what you are looking for.
\item
\href{https://bugs.r-project.org/?GoAheadAndLogIn=1}{Log In}: Provide the appropriate email address and password here to log in to Bugzilla.
\item
\href{https://bugzilla.readthedocs.io/en/latest/using/index.html}{Documentation}: Provides a user guide for R\textquotesingle s Bugzilla.
\end{enumerate}
Several useful shortcuts are available from the landing page:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://bugs.r-project.org/enter_bug.cgi}{Enter a new bug report}
\item
\href{https://bugs.r-project.org/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}{Show open bugs new-to-old}
\item
\href{https://bugs.r-project.org/query.cgi}{Search existing bug reports}
\end{enumerate}
A \href{https://bugs.r-project.org/page.cgi?id=quicksearch.html}{quick search} bar is available on the home page where you can enter a bug number to search or some search terms.
\begin{figure}
\centering
\includegraphics{img/quicksearch.png}
\caption{Screenshot of the quick search bar on the home page of Bugzilla.}
\end{figure}
There is also a section for Common Queries on the home page which includes links to bugs reported and changed in the last 24 hours and last 7 days.
\begin{figure}
\centering
\includegraphics{img/commonquery.png}
\caption{Screenshot of the Common Queries section on the home page of Bugzilla.}
\end{figure}
\hypertarget{ReportingBugs}{%
\chapter{Reporting Bugs}\label{ReportingBugs}}
\hypertarget{what-is-a-bug-in-r}{%
\section{What is a bug in R?}\label{what-is-a-bug-in-r}}
You may find a bug in R if:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
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 \texttt{.C} or \texttt{.Internal}). The error may look like this:
\end{enumerate}
\begin{Shaded}
\begin{Highlighting}[]
\DocumentationTok{\#\# *** caught segfault ***}
\DocumentationTok{\#\# address (nil), cause \textquotesingle{}memory not mapped\textquotesingle{}}
\end{Highlighting}
\end{Shaded}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{1}
\tightlist
\item
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.
\end{enumerate}
\textbf{Note}:
When you are in doubt that there is a bug: (which should be the case most of the time!)
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Make sure whether the bug appears in a clean session of R. Many times, there are variables/commands/functions stored in the workspace 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 \texttt{-\/-vanilla} option.
\item
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 packages and files which are required by that section, and see if the error still appears. Using this approach shall solve most of the errors.
\item
Install R-devel, which is the most recent version of R from \href{https://svn.r-project.org/R/trunk/}{svn} / \href{https://github.com/r-devel/r-svn}{git} or \href{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).
\item
\href{https://r.789695.n4.nabble.com/template/NamlServlet.jtp?macro=search_page\&node=909078\&query=isna\&days=0}{Search on the R-devel mailing 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.
\end{enumerate}
\hypertarget{what-condition-might-not-be-a-bug}{%
\section{What condition might not be a bug?}\label{what-condition-might-not-be-a-bug}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
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.
\item
Issues with \href{https://cran.r-project.org/doc/FAQ/R-FAQ.html\#Why-doesn_0027t-R-think-these-numbers-are-equal_003f}{\emph{seemingly} identical numbers} not being equal (especially floating point numbers) are usually not bugs.
\item
If R is running slower than expected, then this also may not be a bug. Ask someone else to review your code in such a case.
\item
If some function is working, but it is not defined in the best generalised way, then consult someone to look over the code. This may perhaps not be a bug; instead, it might be an alternative way of writing the function.
\end{enumerate}
\hypertarget{checking-if-a-bug-is-already-reported}{%
\section{Checking if a bug is already reported}\label{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:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Save time for you and the developers.
\item
Help you see if the bug is already fixed for the next release.
\item
Lead you to learn what needs to be done to fix it.
\item
Determine if any additional information is needed.
\end{enumerate}
The sections that follow discuss where to check whether a bug is already reported.
\hypertarget{what-are-some-places-where-you-may-find-a-bug}{%
\section{What are some places where you may find a bug?}\label{what-are-some-places-where-you-may-find-a-bug}}
You may find a bug in:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
In the \protect\hyperlink{RCorePkgBug}{R-Core supported packages, their documentations, and/ or in the R language implementation}.
\item
In \protect\hyperlink{nonRCorePkgBug}{packages and/or their documentations which are not supported by the R-Core}.
\end{enumerate}
\hypertarget{ReportBug}{%
\section{How to report a bug?}\label{ReportBug}}
Once you confirm a bug exists, you need to submit a bug report so that it gets fixed.
\hypertarget{RCorePkgBug}{%
\subsection{Bug in the R-Core supported packages, their documentations, and/ or in the R language}\label{RCorePkgBug}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Packages that are supported by the R-Core are labelled with \texttt{Maintainer:\ R\ Core\ Team\ \textless{}[email protected]\textgreater{}}. One simple way to get the information from R is by running the \texttt{maintainer("package\_name")} command.
\item
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-devel, \href{https://www.r-project.org/posting-guide.html\#which_list}{see posting guide}, or to \href{https://bugs.r-project.org/bugzilla/}{Bugzilla}. In the future, we hope to have an option to report an issue to the \href{https://github.com/r-devel/r-svn/issues}{GitHub Mirror of the R svn server}.
\item
In order to report bugs, as well as fixes, using \protect\hyperlink{Bugzilla}{Bugzilla}, please ensure that you have a \protect\hyperlink{bugzilla-account}{Bugzilla account}
\item
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 \href{https://bugs.r-project.org/bugzilla/query.cgi}{search existing bug reports}, using the \href{https://bugs.r-project.org/bugzilla/query.cgi?format=advanced}{advanced search} option here, or \href{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}{show open bugs new-to-old}).
\end{enumerate}
\hypertarget{nonRCorePkgBug}{%
\subsection{Bug in the non R-Core supported packages and/or their documentations}\label{nonRCorePkgBug}}
For packages that are not maintained by the R-Core, the bug reports can be submitted 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 \texttt{DESCRIPTION} file first (e.g.~using \texttt{packageDescription("package\_name")}) to check if a url is provided in the \texttt{BugReports} field. If that is not available, then the package maintainer can be contacted (using \texttt{maintainer("package\_name")}). In R running the function \texttt{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 \texttt{bug.report} is disabled in RStudio, by default. However, if you use \texttt{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.
\hypertarget{good-practices-in-reporting-bugs-expectations-of-a-good-bug-report}{%
\section{Good practices in reporting bugs / Expectations of a good bug report}\label{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.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Include a minimal reproducible example of the bug in your report. The maintainer should be able to quickly reproduce the bug using the minimal example that you provide. Here is a \href{https://stackoverflow.com/questions/5963269/how-to-make-a-great-r-reproducible-example}{community wiki post} on how to make a minimal reproducible example.
\item
Mention the software architecture on which the bug occurred.
\item
Use inbuilt data sets as far as possible.
\end{enumerate}
In addition to the above, here are the \href{https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html}{bug writing guidelines} on Bugzilla. The \href{https://www.r-project.org/bugs.html\#writing-a-good-bug-report}{bug reporting} documentation in R also 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.
\hypertarget{disagreement-with-a-resolution-on-the-bug-tracker}{%
\section{Disagreement with a resolution on the bug tracker}\label{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 to be 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 not carefully thought about in the first place then it 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 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).
\hypertarget{examples-of-bug-reports-submitted-on-bugzilla-or-r-devel-mailing-list}{%
\section{Examples of Bug reports submitted on Bugzilla or R-devel mailing list}\label{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:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17767}{Bug 17767 - Warning about incomplete argument within nlme}: A bug report with a reproducible example, a patch, and a review.
\item
\href{https://stat.ethz.ch/pipermail/r-devel/2019-May/077855.html}{Possible bug when finding shared libraries during staged installation}: A bug report 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 \href{https://stat.ethz.ch/mailman/listinfo/r-devel}{here}).
\item
\href{https://stat.ethz.ch/pipermail/r-devel/2019-February/077393.html}{Bug: time complexity of substring is quadratic as string size and number of substrings increases}: A substring reported by Toby Dylan Hocking and fixed by Tomas Kalibera, Feb 2019 via the R-devel mailing list.
\item
\href{https://stat.ethz.ch/pipermail/r-devel/2019-February/077315.html}{patch for gregexpr(perl=TRUE)}: A gregexpr bug report and patch submitted by Toby Dylan Hocking and merged by Tomas Kalibera, Feb 2019 via the R-devel mailing list.
\end{enumerate}
\hypertarget{see-also-1}{%
\section{See also}\label{see-also-1}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
\href{https://www.r-project.org/bugs.html}{Reporting a bug}
\item
\href{https://mac.r-project.org/man/R-FAQ.html\#R-Bugs}{R FAQ on bugs}
\item
\href{https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html}{Bugzilla guidelines of reporting a bug}
\end{enumerate}
\hypertarget{ReviewBugs}{%
\chapter{Reviewing Bugs}\label{ReviewBugs}}
\hypertarget{how-you-can-help-to-review-bug-reports}{%
\section{How you can help to review bug reports?}\label{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.
\hypertarget{preparing-to-review-bug-reports}{%
\subsection{Preparing to review bug reports}\label{preparing-to-review-bug-reports}}
If you want to review bug reports on Bugzilla, you are required to have a \protect\hyperlink{bugzilla-account}{Bugzilla account}. More details on how you can review a bug report are available on this post on the R Blog: \href{https://blog.r-project.org/2019/10/09/r-can-use-your-help-reviewing-bug-reports/index.html}{R Can Use Your Help: Reviewing Bug Reports}
\hypertarget{classifying-bug-reports}{%
\section{Classifying bug reports}\label{classifying-bug-reports}}
A good bug report is the one which:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Explains clearly how to reproduce the bug.
\item
Includes the version of R, the machine architecture, and the operating system platform on which the bug occurred.
\end{enumerate}
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:
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
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).
\item
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: \texttt{r-patched}, \texttt{r-devel}, or \texttt{r-release} binary builds of R.
\item
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.
\end{enumerate}
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.
\hypertarget{how-to-find-a-bug-report-or-an-issue-to-review}{%
\section{How to find a bug report or an issue to review?}\label{how-to-find-a-bug-report-or-an-issue-to-review}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
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.
\item
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).
\end{enumerate}
\hypertarget{example-of-a-bug-review-submitted-on-bugzilla}{%
\section{Example of a bug review submitted on Bugzilla}\label{example-of-a-bug-review-submitted-on-bugzilla}}
If you would like to see how bugs are reviewed on Bugzilla, the \href{https://bugs.r-project.org/bugzilla/show_bug.cgi?id=16542}{Bug 16542 - nlme:::summary.lmList with unequal outputs per group} 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.
\textbf{Note}:
There is a \texttt{\#bug-reporting} channel on the \href{https://r-contributors.slack.com/}{R Contributors slack} 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.
\hypertarget{see-also-2}{%
\section{See also}\label{see-also-2}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
\href{https://blog.r-project.org/2019/10/09/r-can-use-your-help-reviewing-bug-reports/index.html}{Reviewing bug reports: Blog}
\end{enumerate}
\hypertarget{FindSource}{%
\chapter{Finding the Source}\label{FindSource}}
This chapter discusses how you can have an overview of the R codebase. For instance, where to find the implementation of a base function written in R and where to find a primitive implementation written in C. You may want to find the source code of a function just out of curiosity or maybe to gain more insight into what a particular function is actually doing. Whatever be the case, reading the source code will help you to learn a lot about any function.
\hypertarget{finding-r-source-code}{%
\section{Finding R source code}\label{finding-r-source-code}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
Find the R function with the code of interest. You will always be able to print the top-level function (or use \texttt{View(function\_name)} in RStudio). Looking at the code for the body of this function will reveal what you need to do next:
\end{enumerate}
\begin{itemize}
\item
Can already see code of interest: stop here or skip to step 3 to find the corresponding file in the R sources.
\item
Code of interest is in nested R function: go to step 2.
\item
Top-level function is an S3 generic, identified by a call to \texttt{UseMethod()}. Use \texttt{methods(function\_name)} to see available methods, then go to step 2.
\item
Code of interest is in compiled code, identified by a call to \texttt{.C()}, \texttt{.Call()}, \texttt{.Fortran()}, and \texttt{.External()}, or \texttt{.Internal()} and \texttt{.Primitive()}: go to section on compiled code.
\end{itemize}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{1}
\item
Nested functions or S3 methods may not be exported by the package they are in. If this is the case, the simplest way to view the code is to use \texttt{getAnywhere()} or \texttt{getS3method()}. Now you can keep looking at nested R functions till you find the code of interest or hit a call to compiled code.
\item
Find an R function in the R sources. Two options here:
\end{enumerate}
\begin{itemize}
\tightlist
\item
Search on the internet: For R Core packages, search on the GitHub mirror (\url{https://github.com/r-devel/r-svn}); for recommended packages, use the CRAN mirror (\url{https://github.com/cran}) - this will link to the source on GitHub if available, e.g.~\url{https://github.com/cran/survival}. Note that GitHub search ignores wildcard characters
\end{itemize}
\begin{verbatim}
. , : ; / \ ` ' " = * ! ? # $ & + ^ | ~ < > ( ) { } [ ]
\end{verbatim}
but this does not include \texttt{-} so you can search for a function or S3 method as follows:
\begin{verbatim}
"body <- function" extension:R
"quantile.ecdf <- function" extension:R
\end{verbatim}
\begin{itemize}
\tightlist
\item
Search in the R sources using grep: The \protect\hyperlink{GetStart}{Getting Started} chapter discusses how to download the R sources directly or from the svn repository. Now if the sources are in \texttt{\textasciitilde{}/R-devel}, you can search as follows:
\end{itemize}
\begin{verbatim}
grep -R "body <- function" ~/R-devel/src
grep -R "quantile <- function" ~/R-devel/src/library
\end{verbatim}
Note: The above procedure does not cover S4, R6 or RC generics or methods. Refer \href{https://github.com/jennybc/access-r-source}{accessing R source} for further details.
\hypertarget{finding-c-source-code}{%
\section{Finding C source code}\label{finding-c-source-code}}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
If \texttt{.Internal()} or \texttt{.Primitive()}, find entry point in \texttt{names.c} as described in the Jenny Bryan's post of \href{https://github.com/jennybc/access-r-source}{accessing R source}. For all other calls to compiled code, you can find the entry point from within R. For instance, the body of complete.cases() is
\end{enumerate}
\begin{verbatim}
.External(C_compcases, ...)
\end{verbatim}
\texttt{C\_compcases} inherits from class ``NativeSymbolInfo'' and we can extract the name of the entry point via
\begin{verbatim}
stats:::C_compcases$name
\end{verbatim}
We know that it is in the stats package as we see that when we print complete.cases or look at the help file. This shows us that the entry point is simply ``compcases'' and in fact that is the general convention in R code, that you simply remove the \texttt{C\_} prefix (sometimes \texttt{.F\_} for Fortran code) in the name of the object passed to the first argument of the call.
\begin{enumerate}