├── .all-contributorsrc ├── .github ├── .gitignore ├── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── custom.md │ └── feature_request.md ├── pull_request_template.md └── workflows │ └── publish.yml ├── .gitignore ├── CODE_OF_CONDUCT.md ├── CONDUCT.md ├── CONTRIBUTING.md ├── HOWTO-acknowledge-contributors.md ├── LICENSE.md ├── README.md ├── _quarto.yml ├── chapters ├── additional_resources.qmd ├── developer_tools.qmd ├── documenting.qmd ├── finding_the_source.qmd ├── getting_started.qmd ├── introduction.qmd ├── issue_tracking.qmd ├── lifecycle_of_a_patch.qmd ├── message_translations.qmd ├── news_and_announcements.qmd ├── r_core_developers.qmd ├── reporting_bugs.qmd ├── reviewing_bugs.qmd ├── submitting_feature_requests.qmd ├── testing_pre_release_r_versions.qmd └── where_to_get_help.qmd ├── css └── theme-dark.scss ├── html └── header.html ├── img ├── 02-trgz.png ├── Rlogo.png ├── Rlogo.svg ├── auto-suggestion.png ├── bot-usage.png ├── bugzilla-adv-search-detailed-bug-info.png ├── bugzilla-adv-search-home.png ├── bugzilla-adv-search-search-by-change-history.png ├── bugzilla-adv-search-search-by-people.png ├── bugzilla.png ├── ccby.png ├── commonquery.png ├── cover_page.png ├── cover_page_scriberia.pdf ├── cover_page_scriberia.png ├── cover_page_scriberia.pptx ├── edit_icon.png ├── favicon.png ├── feature-requests.png ├── information.svg ├── lightbulb.svg ├── quicksearch.png ├── r-dev-guide-without-text.jpg ├── r-development-guide.jpg ├── rsvn_PR_automatic_checks.png ├── rsvn_PR_created.png ├── rsvn_PR_message.png ├── rsvn_checks_results.png ├── rsvn_commit_message.png ├── rsvn_commit_pre_PR.png ├── rsvn_edit_file.png ├── rsvn_file_to_edit.png ├── squarebuttons.png ├── translate_automatic_translation.png ├── translate_button.png ├── translate_component.png ├── translate_dialog.png ├── translate_string_and_save.png └── unfinished_strings_translate.png ├── index.qmd ├── rdevguide.Rproj └── tex ├── frontpage.tex └── preamble.tex /.all-contributorsrc: -------------------------------------------------------------------------------- 1 | { 2 | "files": [ 3 | "README.md" 4 | ], 5 | "imageSize": 100, 6 | "commit": false, 7 | "contributors": [ 8 | { 9 | "login": "hturner", 10 | "name": "Heather Turner", 11 | "avatar_url": "https://avatars.githubusercontent.com/u/3343008?v=4", 12 | "profile": "https://www.heatherturner.net/", 13 | "contributions": [ 14 | "content", 15 | "code", 16 | "maintenance", 17 | "mentoring", 18 | "projectManagement", 19 | "review", 20 | "fundingFinding", 21 | "question", 22 | "eventOrganizing", 23 | "talk" 24 | ] 25 | }, 26 | { 27 | "login": "SaranjeetKaur", 28 | "name": "Saranjeet Kaur", 29 | "avatar_url": "https://avatars.githubusercontent.com/u/28556616?v=4", 30 | "profile": "https://saranjeetkaur.github.io/About-Me/", 31 | "contributions": [ 32 | "content", 33 | "doc", 34 | "ideas", 35 | "fundingFinding", 36 | "question", 37 | "eventOrganizing", 38 | "talk", 39 | "video", 40 | "review", 41 | "example", 42 | "research" 43 | ] 44 | }, 45 | { 46 | "login": "MayaGans", 47 | "name": "Maya Gans", 48 | "avatar_url": "https://avatars.githubusercontent.com/u/6053906?v=4", 49 | "profile": "http://maya.rbind.io", 50 | "contributions": [ 51 | "infra" 52 | ] 53 | }, 54 | { 55 | "login": "willingc", 56 | "name": "Carol Willing", 57 | "avatar_url": "https://avatars.githubusercontent.com/u/2680980?v=4", 58 | "profile": "https://www.willingconsulting.com", 59 | "contributions": [ 60 | "review" 61 | ] 62 | }, 63 | { 64 | "login": "llrs", 65 | "name": "Lluís", 66 | "avatar_url": "https://avatars.githubusercontent.com/u/6818218?v=4", 67 | "profile": "http://llrs.dev", 68 | "contributions": [ 69 | "review", 70 | "content", 71 | "question", 72 | "research", 73 | "doc", 74 | "example", 75 | "maintenance" 76 | ] 77 | }, 78 | { 79 | "login": "tdhock", 80 | "name": "Toby Dylan Hocking", 81 | "avatar_url": "https://avatars.githubusercontent.com/u/932850?v=4", 82 | "profile": "http://tdhock.github.io", 83 | "contributions": [ 84 | "review", 85 | "example", 86 | "research", 87 | "question" 88 | ] 89 | }, 90 | { 91 | "login": "bettinagruen", 92 | "name": "bettinagruen", 93 | "avatar_url": "https://avatars.githubusercontent.com/u/3341603?v=4", 94 | "profile": "https://github.com/bettinagruen", 95 | "contributions": [ 96 | "review", 97 | "research", 98 | "question" 99 | ] 100 | }, 101 | { 102 | "login": "mmaechler", 103 | "name": "Martin Mächler", 104 | "avatar_url": "https://avatars.githubusercontent.com/u/995722?v=4", 105 | "profile": "http://stat.ethz.ch/~maechler", 106 | "contributions": [ 107 | "review" 108 | ] 109 | }, 110 | { 111 | "login": "anelda", 112 | "name": "Anelda van der Walt", 113 | "avatar_url": "https://avatars.githubusercontent.com/u/7215014?v=4", 114 | "profile": "http://www.talarify.co.za", 115 | "contributions": [ 116 | "review" 117 | ] 118 | }, 119 | { 120 | "login": "mine-cetinkaya-rundel", 121 | "name": "Mine Cetinkaya-Rundel", 122 | "avatar_url": "https://avatars.githubusercontent.com/u/5965649?v=4", 123 | "profile": "http://mine-cr.com", 124 | "contributions": [ 125 | "review" 126 | ] 127 | }, 128 | { 129 | "login": "MichaelChirico", 130 | "name": "Michael Chirico", 131 | "avatar_url": "https://avatars.githubusercontent.com/u/7606389?v=4", 132 | "profile": "https://github.com/MichaelChirico", 133 | "contributions": [ 134 | "review", 135 | "question", 136 | "content", 137 | "doc", 138 | "research" 139 | ] 140 | }, 141 | { 142 | "login": "elinw", 143 | "name": "Elin Waring", 144 | "avatar_url": "https://avatars.githubusercontent.com/u/754813?v=4", 145 | "profile": "http://officialjoomlabook.com", 146 | "contributions": [ 147 | "question" 148 | ] 149 | }, 150 | { 151 | "login": "lawremi", 152 | "name": "Michael Lawrence", 153 | "avatar_url": "https://avatars.githubusercontent.com/u/158190?v=4", 154 | "profile": "https://github.com/lawremi", 155 | "contributions": [ 156 | "review", 157 | "ideas", 158 | "mentoring" 159 | ] 160 | }, 161 | { 162 | "login": "gmbecker", 163 | "name": "Gabe Becker", 164 | "avatar_url": "https://avatars.githubusercontent.com/u/908721?v=4", 165 | "profile": "https://github.com/gmbecker", 166 | "contributions": [ 167 | "review", 168 | "question" 169 | ] 170 | }, 171 | { 172 | "login": "krlmlr", 173 | "name": "Kirill Müller", 174 | "avatar_url": "https://avatars.githubusercontent.com/u/1741643?v=4", 175 | "profile": "https://github.com/krlmlr", 176 | "contributions": [ 177 | "question" 178 | ] 179 | }, 180 | { 181 | "login": "lionel-", 182 | "name": "Lionel Henry", 183 | "avatar_url": "https://avatars.githubusercontent.com/u/4465050?v=4", 184 | "profile": "https://github.com/lionel-", 185 | "contributions": [ 186 | "question" 187 | ] 188 | }, 189 | { 190 | "login": "HayesJohnD", 191 | "name": "John Hayes", 192 | "avatar_url": "https://avatars.githubusercontent.com/u/66183716?v=4", 193 | "profile": "https://github.com/HayesJohnD", 194 | "contributions": [ 195 | "review" 196 | ] 197 | }, 198 | { 199 | "login": "nbenn", 200 | "name": "nbenn", 201 | "avatar_url": "https://avatars.githubusercontent.com/u/3158446?v=4", 202 | "profile": "https://github.com/nbenn", 203 | "contributions": [ 204 | "review", 205 | "research", 206 | "question" 207 | ] 208 | }, 209 | { 210 | "login": "benubah", 211 | "name": "Ben", 212 | "avatar_url": "https://avatars.githubusercontent.com/u/11357251?v=4", 213 | "profile": "https://github.com/benubah", 214 | "contributions": [ 215 | "content", 216 | "review", 217 | "research", 218 | "question" 219 | ] 220 | }, 221 | { 222 | "login": "itsdebartha", 223 | "name": "Debartha Paul", 224 | "avatar_url": "https://avatars.githubusercontent.com/u/53690728?v=4", 225 | "profile": "https://github.com/itsdebartha", 226 | "contributions": [ 227 | "content" 228 | ] 229 | }, 230 | { 231 | "login": "lgibson7", 232 | "name": "Lydia Gibson, MS, GStat", 233 | "avatar_url": "https://avatars.githubusercontent.com/u/87203716?v=4", 234 | "profile": "https://github.com/lgibson7", 235 | "contributions": [ 236 | "content", 237 | "doc", 238 | "ideas" 239 | ] 240 | }, 241 | { 242 | "login": "PatriLoto", 243 | "name": "Patricia A. Loto", 244 | "avatar_url": "https://avatars.githubusercontent.com/u/39300655?v=4", 245 | "profile": "https://patricia-loto.netlify.app/", 246 | "contributions": [ 247 | "content", 248 | "doc", 249 | "ideas" 250 | ] 251 | }, 252 | { 253 | "login": "ivelasq", 254 | "name": "Isabella Velásquez", 255 | "avatar_url": "https://avatars.githubusercontent.com/u/12236152?v=4", 256 | "profile": "http://ivelasq.rbind.io", 257 | "contributions": [ 258 | "content", 259 | "doc", 260 | "ideas" 261 | ] 262 | }, 263 | { 264 | "login": "cjrace", 265 | "name": "Cam Race", 266 | "avatar_url": "https://avatars.githubusercontent.com/u/52536248?v=4", 267 | "profile": "https://github.com/cjrace", 268 | "contributions": [ 269 | "infra", 270 | "content", 271 | "doc" 272 | ] 273 | }, 274 | { 275 | "login": "shannonpileggi", 276 | "name": "Shannon Pileggi", 277 | "avatar_url": "https://avatars.githubusercontent.com/u/17747575?v=4", 278 | "profile": "https://www.pipinghotdata.com/", 279 | "contributions": [ 280 | "content", 281 | "doc", 282 | "ideas" 283 | ] 284 | }, 285 | { 286 | "login": "pmur002", 287 | "name": "Paul Murrell", 288 | "avatar_url": "https://avatars.githubusercontent.com/u/2044052?v=4", 289 | "profile": "https://github.com/pmur002", 290 | "contributions": [ 291 | "content" 292 | ] 293 | }, 294 | { 295 | "login": "zkamvar", 296 | "name": "Zhian N. Kamvar", 297 | "avatar_url": "https://avatars.githubusercontent.com/u/3639446?v=4", 298 | "profile": "http://zkamvar.netlify.app", 299 | "contributions": [ 300 | "content", 301 | "doc", 302 | "ideas" 303 | ] 304 | }, 305 | { 306 | "login": "jmaspons", 307 | "name": "Joan Maspons", 308 | "avatar_url": "https://avatars.githubusercontent.com/u/102644?v=4", 309 | "profile": "https://github.com/jmaspons", 310 | "contributions": [ 311 | "infra" 312 | ] 313 | }, 314 | { 315 | "login": "hanneoberman", 316 | "name": "Hanne Oberman", 317 | "avatar_url": "https://avatars.githubusercontent.com/u/38891540?v=4", 318 | "profile": "http://hanneoberman.github.io", 319 | "contributions": [ 320 | "content" 321 | ] 322 | }, 323 | { 324 | "login": "bastistician", 325 | "name": "Sebastian Meyer", 326 | "avatar_url": "https://avatars.githubusercontent.com/u/4366501?v=4", 327 | "profile": "https://www.imbe.med.fau.de/person/sebastian-meyer/", 328 | "contributions": [ 329 | "ideas", 330 | "research", 331 | "question" 332 | ] 333 | }, 334 | { 335 | "login": "hfrick", 336 | "name": "Hannah Frick", 337 | "avatar_url": "https://avatars.githubusercontent.com/u/12950918?v=4", 338 | "profile": "http://www.frick.ws", 339 | "contributions": [ 340 | "doc", 341 | "ideas" 342 | ] 343 | }, 344 | { 345 | "login": "SJaffa", 346 | "name": "S Jaffa", 347 | "avatar_url": "https://avatars.githubusercontent.com/u/13678317?v=4", 348 | "profile": "https://github.com/SJaffa", 349 | "contributions": [ 350 | "content", 351 | "doc" 352 | ] 353 | }, 354 | { 355 | "login": "bjungbogati", 356 | "name": "Binod Jung Bogati", 357 | "avatar_url": "https://avatars.githubusercontent.com/u/8600091?v=4", 358 | "profile": "http://bjungbogati.com.np", 359 | "contributions": [ 360 | "content", 361 | "doc" 362 | ] 363 | }, 364 | { 365 | "login": "daroczig", 366 | "name": "Gergely Daróczi", 367 | "avatar_url": "https://avatars.githubusercontent.com/u/495736?v=4", 368 | "profile": "https://daroczig.github.io", 369 | "contributions": [ 370 | "review" 371 | ] 372 | }, 373 | { 374 | "login": "razekmh", 375 | "name": "Mahmoud Abdelrazek", 376 | "avatar_url": "https://avatars.githubusercontent.com/u/44040283?v=4", 377 | "profile": "https://github.com/razekmh", 378 | "contributions": [ 379 | "content", 380 | "doc" 381 | ] 382 | }, 383 | { 384 | "login": "EllaKaye", 385 | "name": "Ella Kaye", 386 | "avatar_url": "https://avatars.githubusercontent.com/u/7222491?v=4", 387 | "profile": "https://ellakaye.co.uk", 388 | "contributions": [ 389 | "code", 390 | "infra" 391 | ] 392 | }, 393 | { 394 | "login": "ccamara", 395 | "name": "Carlos Cámara", 396 | "avatar_url": "https://avatars.githubusercontent.com/u/706549?v=4", 397 | "profile": "http://carloscamara.es/en", 398 | "contributions": [ 399 | "maintenance", 400 | "doc" 401 | ] 402 | } 403 | ], 404 | "contributorsPerLine": 7, 405 | "projectName": "rdevguide", 406 | "projectOwner": "r-devel", 407 | "repoType": "github", 408 | "repoHost": "https://github.com", 409 | "skipCi": true, 410 | "commitConvention": "angular", 411 | "commitType": "docs" 412 | } 413 | -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Desktop (please complete the following information):** 27 | - OS: [e.g. iOS] 28 | - Browser [e.g. chrome, safari] 29 | - Version [e.g. 22] 30 | 31 | **Smartphone (please complete the following information):** 32 | - Device: [e.g. iPhone6] 33 | - OS: [e.g. iOS8.1] 34 | - Browser [e.g. stock browser, safari] 35 | - Version [e.g. 22] 36 | 37 | **Additional context** 38 | Add any other context about the problem here. 39 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/custom.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Custom issue template 3 | about: Describe this issue template's purpose here. 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | 4 | ### Summary 5 | 6 | 7 | 8 | *Lorem ipsum dolor sit amet, consectetur adipiscing.* 9 | 10 | 12 | 13 | - [ ] *Lorem ipsum dolor sit amet, consectetur adipiscing.* 14 | - [ ] *Lorem ipsum dolor sit amet, consectetur adipiscing.* 15 | 16 | 17 | 18 | Fixes # 19 | 20 | ### Checklist for adding a new chapter or chapters 21 | 22 | 24 | 25 | - [ ] Have you updated the [Quick start to the guide](introduction.qmd#quick-start-to-the-guide) accordingly? 26 | - [ ] Have you updated the `chapters` field of `_quarto.yml`? This determines the chapter ordering. 27 | - [ ] Have you named the new `.qmd` files using lower case, with words separated by `_` if required? 28 | 29 | ### What should a reviewer concentrate their feedback on? 30 | 31 | 32 | 33 | - [ ] *Lorem ipsum dolor sit amet, consectetur adipiscing.* 34 | - [ ] Everything looks ok? 35 | 36 | ### Acknowledging contributors 37 | 38 | List any contributions that need adding to the [table of contributors](https://github.com/r-devel/rdevguide/blob/main/README.md#contributors-). Common contributions are `content` (adding to the guide), `doc` (e.g. README, wiki), `infra` (e.g. GitHub action), and `maintenance` (e.g. fixing links). See the full key to [Contribution Types](https://allcontributors.org/docs/en/emoji-key). 39 | 40 | - [ ] Please add @ for . Please add @ for , . 41 | - [ ] **For reviewers**: All relevant contributions have been added, including reviewers, mentors, contributors to the ideas/planning. See [how to acknowledge contributors](https://github.com/r-devel/rdevguide/blob/main/HOWTO-acknowledge-contributors.md). -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | on: 2 | workflow_dispatch: 3 | push: 4 | branches: main 5 | 6 | name: Quarto Publish 7 | 8 | jobs: 9 | build-deploy: 10 | runs-on: ubuntu-latest 11 | permissions: 12 | contents: write 13 | steps: 14 | - name: Check out repository 15 | uses: actions/checkout@v4 16 | 17 | - name: Set up Quarto 18 | uses: quarto-dev/quarto-actions/setup@v2 19 | with: 20 | # To install LaTeX to build PDF book 21 | tinytex: true 22 | 23 | - name: Render and Publish 24 | uses: quarto-dev/quarto-actions/publish@v2 25 | with: 26 | target: gh-pages 27 | env: 28 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 29 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | .DS_Store 6 | docs/ 7 | rdevguide.rds 8 | rdevguide.log 9 | rdevguide.tex 10 | 11 | # temp files 12 | *~ 13 | 14 | /.quarto/ 15 | _book -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, religion, or sexual identity 10 | and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement at 63 | rcwg-coc-team@gaggle.email. 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behavior deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behavior was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series 86 | of actions. 87 | 88 | **Consequence**: A warning with consequences for continued behavior. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or 93 | permanent ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behavior. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behavior, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within 113 | the community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.0, available at 119 | https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. 120 | 121 | Community Impact Guidelines were inspired by [Mozilla's code of conduct 122 | enforcement ladder](https://github.com/mozilla/diversity). 123 | 124 | [homepage]: https://www.contributor-covenant.org 125 | 126 | For answers to common questions about this code of conduct, see the FAQ at 127 | https://www.contributor-covenant.org/faq. Translations are available at 128 | https://www.contributor-covenant.org/translations. 129 | -------------------------------------------------------------------------------- /CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Code of Conduct 2 | 3 | As contributors and maintainers of this project, we pledge to respect all people who 4 | contribute through reporting issues, posting feature requests, updating documentation, 5 | submitting pull requests or patches, and other activities. 6 | 7 | We are committed to making participation in this project a harassment-free experience for 8 | everyone, regardless of level of experience, gender, gender identity and expression, 9 | sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. 10 | 11 | Examples of unacceptable behavior by participants include the use of sexual language or 12 | imagery, derogatory comments or personal attacks, trolling, public or private harassment, 13 | insults, or other unprofessional conduct. 14 | 15 | Project maintainers have the right and responsibility to remove, edit, or reject comments, 16 | commits, code, wiki edits, issues, and other contributions that are not aligned to this 17 | Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed 18 | from the project team. 19 | 20 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by 21 | opening an issue or contacting one or more of the project maintainers. 22 | 23 | This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/), version 1.0.0, available at 24 | https://contributor-covenant.org/version/1/0/0/ 25 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | ## Without write access 4 | 5 | Corrections, suggestions and general improvements are welcome as [issue submissions](issues/new). 6 | 7 | You can also suggest changes by editing the .Rmd files that are at the root of this repository and submitting a pull request. Please target your pull requests to the `main` branch. 8 | 9 | ## With write access 10 | 11 | You can push directly to `main` for small fixes. Please use PRs to `main` for discussing larger updates - try to limit to one section or at least one chapter in each PR, so that changes are easier to review. 12 | -------------------------------------------------------------------------------- /HOWTO-acknowledge-contributors.md: -------------------------------------------------------------------------------- 1 | To recognise the contributions made on this repository we use the [All Contributors](https://allcontributors.org/) Bot. 2 | Our aim is to recognise all contributors including those that don't push code. 3 | Types of contribution supported by the bot include: 4 | - Creating a new Pull Request or Issue on this repository 5 | - Giving talks based on this repository 6 | - Mentoring contributions to this repository 7 | - Reviewing Pull Requests on this repository 8 | - Reporting or working on accessibility issues related to this repository 9 | - Providing links to podcasts, interviews, or any audio material, blogposts, tutorials, talks, videos, slides, repository, and recordings that mention this repository or mention the R Development Guide. 10 | These links can be shared through a pull request or by opening a new issue. 11 | - Adding content to the Wiki on this repository 12 | - Creating logo/iconography/visual design/etc. for this project 13 | - Organising events related to this project 14 | - Providing financial support for this project 15 | - Support the infrastructure required for this project 16 | - Help with the maintenance of this repository 17 | - Promoting this repository and project 18 | - Answering Questions in Issues, Slack, etc. 19 | - Translating content of this repository 20 | - Conducting literature review for the work on this project 21 | 22 | # How to add Contributor(s)? 23 | 24 | 1. To add a Contributor to this repository, comment on the relevant Issue or Pull Request, asking `@all-contributors` to add a Contributor: 25 | 26 | ```sh 27 | @all-contributors please add @ for 28 | ``` 29 | 30 | 2. After this the bot will create a Pull Request to add the Contributor and reply to your comment with the pull request details. 31 | ![Example of using the All Contributors bot](img/bot-usage.png) 32 | 33 | 3. Once the repository Admins review and approve this Pull Request, the Contributor will be listed on the repository. 34 | 35 | 4. Multiple Contributors can also be added at the same time using a single line or multiple lines: 36 | 37 | - Using single line 38 | ```sh 39 | @all-contributors please add @ for . please add @ for . 40 | ``` 41 | 42 | - Using multiple lines 43 | ```sh 44 | @all-contributors 45 | please add @ for . 46 | please add @ for . 47 | ``` 48 | 49 | 5. Multiple contributions can be included separated by comma (,): 50 | 51 | ```sh 52 | @all-contributors please add @ for , , 53 | ``` 54 | 55 | ## Note: 56 | 57 | - A list of valid contribution types is available on the [Emoji Key (and Contribution Types)](https://allcontributors.org/docs/en/emoji-key) page. 58 | Replace `` with the appropriate keyword available in the `Type` column of the [Emoji Key table](https://allcontributors.org/docs/en/emoji-key#table). 59 | 60 | - The bot uses [basic Natural Language Parsing](https://github.com/all-contributors/app/blob/master/lib/parse-comment.js) to determine the intent of your comment. Hence, your request to the bot doesn't need to be perfect. For example, the following will work too: 61 | ```sh 62 | Jane you have written excellent documentation and your infrastructure work has been great too. Let's add `@jane.doe23` for her contributions. cc `@all-contributors` 63 | ``` 64 | If you precede the contributor's username with `@` as shown above, then the bot will work best in parsing the comment correctly. Otherwise, the bot may not correctly identify the user. 65 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Non-software content in this project is licensed under a [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license. 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) 2 | 3 | # A Guide for Contributing to R Core 4 | 5 | [![All Contributors](https://img.shields.io/badge/all_contributors-37-orange.svg?style=flat-square)](#contributors-) 6 | 7 | 8 | This guide is a work in progress, inspired by http://devguide.python.org/. It is deployed at https://contributor.r-project.org/rdevguide/. 9 | 10 | ## Background Resources 11 | 12 | A list of existing resources on R core development that we can use for reference or that we should document in the guide is given in the [Wiki for this repo](https://github.com/r-devel/rdevguide/wiki). 13 | 14 | ## Contributing 15 | 16 | ### Without write access 17 | 18 | Corrections, suggestions and general improvements are welcome as [issue submissions](issues/new). 19 | 20 | You can also suggest changes by editing the `.qmd` files that are in the `chapters/` folder at the root of this repository and submitting a pull request. Please target your pull requests to the `main` branch. 21 | 22 | ### With write access 23 | 24 | You can push directly to `main` for small fixes. Please use PRs to `main` for discussing larger updates - try to limit to one section or at least one chapter in each PR, so that changes are easier to review. 25 | 26 | ## Editing notes 27 | 28 | * Images must be included in the source, not provided as URLs, for the PDF book to compile. 29 | * Images should have alt text for accessibility - note this is shown as a caption in the EPUB version. 30 | 31 | ## Technical details 32 | 33 | Deployment is done via GitHub Actions, as specified in the [publish.yml](https://github.com/r-devel/rdevguide/blob/main/.github/workflows/publish.yml) workflow: 34 | 35 | - whenever there's a push to main, the book is built and its content is put on the `gh-pages` branch, triggering the github-pages bot to deploy to . 36 | 37 | If you want to render the guide locally, you need to download and install the Quarto CLI (command line interface) as documented on the [Quarto website](https://quarto.org/docs/get-started/). Then, from the command line (not the R console), run: 38 | 39 | ```quarto preview``` 40 | 41 | to preview changes in real time, or: 42 | 43 | ```quarto render``` 44 | 45 | to generate the book in the `_book/` folder. This will also generate the PDF and ePub versions of the book, so takes a little longer. You can open the HTML version of the guide from the command line via `open _book/index.html`. 46 | 47 | If you are using RStudio, VS Code or Positron, you can use the Preview button (VS Code/Positron) or Render button (RStudio) instead. 48 | 49 | ## Code of Conduct 50 | 51 | Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). 52 | By participating in this project you agree to abide by its terms. 53 | 54 | ## Acknowledgements 55 | 56 | This book started using Sean Kross' [minimal bookdown example](https://github.com/seankross/bookdown-start) as described on their [blog](http://seankross.com/2016/11/17/How-to-Start-a-Bookdown-Book.html). 57 | 58 | This README borrowed ideas from [ropensci/dev_guide](https://github.com/ropensci/dev_guide). 59 | 60 | ## Contributors ✨ 61 | 62 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): 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 |
Heather Turner
Heather Turner
🖋 💻 🚧 🧑‍🏫 📆 👀 🔍 💬 📋 📢		Saranjeet Kaur
Saranjeet Kaur
🖋 📖 🤔 🔍 💬 📋 📢 📹 👀 💡 🔬		Maya Gans
Maya Gans
🚇		Carol Willing
Carol Willing
👀		Lluís
Lluís
👀 🖋 💬 🔬 📖 💡 🚧		Toby Dylan Hocking
Toby Dylan Hocking
👀 💡 🔬 💬		bettinagruen
bettinagruen
👀 🔬 💬
Martin Mächler
Martin Mächler
👀		Anelda van der Walt
Anelda van der Walt
👀		Mine Cetinkaya-Rundel
Mine Cetinkaya-Rundel
👀		Michael Chirico
Michael Chirico
👀 💬 🖋 📖 🔬		Elin Waring
Elin Waring
💬		Michael Lawrence
Michael Lawrence
👀 🤔 🧑‍🏫		Gabe Becker
Gabe Becker
👀 💬
Kirill Müller
Kirill Müller
💬		Lionel Henry
Lionel Henry
💬		John Hayes
John Hayes
👀		nbenn
nbenn
👀 🔬 💬		Ben
Ben
🖋 👀 🔬 💬		Debartha Paul
Debartha Paul
🖋		Lydia Gibson, MS, GStat
Lydia Gibson, MS, GStat
🖋 📖 🤔
Patricia A. Loto
Patricia A. Loto
🖋 📖 🤔		Isabella Velásquez
Isabella Velásquez
🖋 📖 🤔		Cam Race
Cam Race
🚇 🖋 📖		Shannon Pileggi
Shannon Pileggi
🖋 📖 🤔		Paul Murrell
Paul Murrell
🖋		Zhian N. Kamvar
Zhian N. Kamvar
🖋 📖 🤔		Joan Maspons
Joan Maspons
🚇
Hanne Oberman
Hanne Oberman
🖋		Sebastian Meyer
Sebastian Meyer
🤔 🔬 💬		Hannah Frick
Hannah Frick
📖 🤔		S Jaffa
S Jaffa
🖋 📖		Binod Jung Bogati
Binod Jung Bogati
🖋 📖		Gergely Daróczi
Gergely Daróczi
👀		Mahmoud Abdelrazek
Mahmoud Abdelrazek
🖋 📖
Ella Kaye
Ella Kaye
💻 🚇		Carlos Cámara
Carlos Cámara
🚧 📖
120 | 121 | 122 | 123 | 124 | 125 | 126 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! 127 | -------------------------------------------------------------------------------- /_quarto.yml: -------------------------------------------------------------------------------- 1 | project: 2 | type: book 3 | 4 | book: 5 | title: "R Development Guide" 6 | author: "R Contribution Working Group" 7 | date: today 8 | favicon: img/favicon.png 9 | site-url: https://contributor.r-project.org/rdevguide 10 | repo-url: https://github.com/r-devel/rdevguide 11 | repo-branch: main 12 | repo-actions: [edit, issue] 13 | sharing: [linkedin] 14 | open-graph: true 15 | image: img/cover_page_scriberia.png 16 | downloads: [pdf, epub] 17 | chapters: 18 | - index.qmd 19 | - chapters/introduction.qmd 20 | - chapters/getting_started.qmd 21 | - chapters/issue_tracking.qmd 22 | - chapters/reporting_bugs.qmd 23 | - chapters/submitting_feature_requests.qmd 24 | - chapters/reviewing_bugs.qmd 25 | - chapters/finding_the_source.qmd 26 | - chapters/lifecycle_of_a_patch.qmd 27 | - chapters/documenting.qmd 28 | - chapters/message_translations.qmd 29 | - chapters/testing_pre_release_r_versions.qmd 30 | - chapters/where_to_get_help.qmd 31 | - chapters/news_and_announcements.qmd 32 | - chapters/developer_tools.qmd 33 | - chapters/additional_resources.qmd 34 | - chapters/r_core_developers.qmd 35 | 36 | format: 37 | html: 38 | theme: 39 | light: cosmo 40 | dark: [cosmo, css/theme-dark.scss] 41 | include-in-header: html/header.html 42 | description-meta: "This guide is a comprehensive resource for contributors (from all levels, beginners, intermediate, and seasoned) to the R project, facilitating their onboarding and helping them navigate the contribution process." 43 | pdf: 44 | documentclass: scrreprt 45 | include-in-header: tex/preamble.tex 46 | include-before-body: tex/frontpage.tex 47 | epub: 48 | cover-image: img/cover_page_scriberia.png 49 | 50 | # book_filename: "rdevguide" 51 | # chapter_name: "Chapter " 52 | # repo: https://github.com/r-devel/rdevguide 53 | # url: 'https\://contributor.r-project.org/rdevguide/' 54 | # github-repo: "r-devel/rdevguide" 55 | # output_dir: docs 56 | # clean: [packages.bib, bookdown.bbl] 57 | # new_session: yes 58 | # edit: https://github.com/r-devel/rdevguide/edit/main/%s 59 | # delete_merged_file: true 60 | -------------------------------------------------------------------------------- /chapters/additional_resources.qmd: -------------------------------------------------------------------------------- 1 | # Additional resources {#AdditionalResources} 2 | 3 | There are a number of further resources to help with contributions to R. 4 | 5 | ## R Contributor site 6 | 7 | Contains information for people interested in contributing to R core, including details for the [R Contribution Working Group](https://contributor.r-project.org/working-group), the [R Contributors Slack workspace](https://contributor.r-project.org/slack) and upcoming [R Contributor events and meetups](https://contributor.r-project.org/events/). 8 | 9 | ## R developer page 10 | 11 | The [R developer page](https://developer.r-project.org/) contains information about the plans of the R Core Team and details on the R release process, as well as pointers to technical write-ups including the [R blog](https://blog.r-project.org/). 12 | 13 | ## R manuals 14 | 15 | There are a number of manuals created and included with R installations. The original latest and development versions of these are available from the [R Manuals site](https://cran.r-project.org/manuals.html). Note that the versions included on the site are created with Debian Linux. While there may be some variation for Windows and Mac manuals, most parts will be identical regardless of platform. 16 | 17 | Particular manuals that might be of interest to R contributors are: 18 | 19 | - [R installation and administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html) - gives more details on building R from source. 20 | - [R internals](https://cran.r-project.org/doc/manuals/r-release/R-ints.html) - for those who want to read deeper into the internals R, for example, it contains chapters on special data types used in the C code, internal and primitive functions and details of graphics devices. 21 | - [R language definition](https://cran.r-project.org/doc/manuals/r-release/R-lang.html) - an in depth overview of the R language, helpful for developing more advanced R knowledge from a user's perspective. 22 | 23 | There is a [new re-styled R manuals site built with Quarto](https://rstudio.github.io/r-manuals/) that has been produced to make searching and navigating the manuals easier in a web browser. This site is automatically built from the original manuals site using a number of scripts in the [r-manuals GitHub repo](https://github.com/rstudio/r-manuals). 24 | -------------------------------------------------------------------------------- /chapters/developer_tools.qmd: -------------------------------------------------------------------------------- 1 | # Developer Tools {#DevTools} 2 | 3 | This chapter lists resources and tools which R developers may use. Here we will go over some commonly used tools that are relevant to R’s workflow. As there are several ways to accomplish these tasks, this chapter reflects methods suitable for new contributors. Experienced contributors may desire a different approach. 4 | 5 | ## Subversion (svn) client 6 | 7 | Subversion (svn) is a version control system that tracks any changes made to files and directories. You can install either the [TortoiseSVN](https://tortoisesvn.net/) (command line tool, and Windows Explorer integration) or the [SlikSVN](https://sliksvn.com/download/) (just the command line tool) client. They have Windows installers and can be used from Windows cmd or RStudio terminal. 8 | 9 | Some resources for learning subversion commands: 10 | 11 | 1. [Apache Subversion quick start guide](http://subversion.apache.org/quick-start) 12 | 13 | 2. [TortoiseSVN commands](https://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-cli-main.html) 14 | 15 | 3. [SlikSVN basics](https://sliksvn.com/support/subversion-basics-using-check-out-update-check-in-commit/) 16 | 17 | 4. [Subversion book](http://svnbook.red-bean.com/) 18 | 19 | ## Globally search for a regular expression and print matching lines (grep) 20 | 21 | [grep](https://en.wikipedia.org/wiki/Grep) is a command line utility for searching plain text data sets for lines that match a regular expression. Refer the [grep manual](https://www.gnu.org/software/grep/manual/grep.html) for more commands. 22 | 23 | ## Git 24 | 25 | [Git](https://en.wikipedia.org/wiki/Git) is also a version control system for tracking changes in any files and directories. View [git documentation](https://git-scm.com/doc) for learning git commands. 26 | 27 | ## GitHub 28 | 29 | Some resources that are useful while using GitHub are: 30 | 31 | 1. [Creating a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) 32 | 33 | 2. [Opening an issue from code](https://docs.github.com/en/github/managing-your-work-on-github/opening-an-issue-from-code) 34 | 35 | 3. [Resolving a merge conflict on GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github) 36 | -------------------------------------------------------------------------------- /chapters/documenting.qmd: -------------------------------------------------------------------------------- 1 | # Documenting {#Doc} 2 | 3 | R has a substantial body of documentation, comprising help files for the core packages and a set of manuals aimed at users (An Introduction to R, R Data Import/Export), system administrators (R Installation and Administration) and developers (Writing R Extensions, The R language definition, and R Internals). This documentation was developed by the R Core Team with input from external contributors. The continuing involvement of the user community is important in maintaining this valuable documentation. 4 | 5 | The involvement of the community takes many forms, from contributing content, to making bug reports or raising an issue when the documentation could be more complete or made easier to follow. 6 | 7 | This chapter is about the ways people can contribute to R's documentation, with guidance on how to do that. Any time you feel that you can clarify or fill gaps in existing documentation, your contribution is welcome and appreciated. If you find it difficult to deal with the markup formatting language used in the source files, you can ask for help with that part too. Please do not let the material in this chapter stand between the documentation and your desire to help out. However, not every good faith effort to change or extend the documentation will be accepted - sometimes the suggested changes may be incorrect; other times, while a change in wording may make some things clearer and easier to understand, the finer details of some corner case may become less clear, leading to the suggested changes being declined or modified by a member of R Core before applying them (if they agree the issue is important enough to fix). 8 | 9 | ## Helping with documentation 10 | 11 | Maintaining the accuracy of R's documentation and keeping a high level of quality takes a lot of effort. Community members, like you, help with writing, editing, and updating content, and these contributions are appreciated and welcomed. 12 | 13 | Looking at pre-existing documentation source files can be very helpful when getting started. 14 | 15 | You can directly search for [documentation issues/bugs on Bugzilla](https://bugs.r-project.org/buglist.cgi?component=Documentation&list_id=22501&product=R&resolution=---). Issues vary from typos to unclear documentation and items lacking documentation. 16 | 17 | If you see a documentation issue that you would like to tackle, you can leave a comment on the issue saying you are going to try to solve the issue and mention roughly how long you think you will take to do so (this allows others to take on the issue if you happen to forget or lose interest). 18 | 19 | ## Reporting documentation bugs 20 | 23 | 24 | To suggest improvements to the R manuals, report typos or bugs in the R manuals, or to raise issues related to documentation in packages maintained by the R Core Team, follow the usual guidance for [reporting bugs in R](#RCorePkgBug). 25 | 26 | To report bugs or typos in the documentation of a package that is not maintained by the R Core Team, follow the guidance for [reporting bugs in contributed packages](#nonRCorePkgBug). 27 | 28 | **Note**: 29 | 30 | There is a `#core-documentation` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can get feedback before reporting an issue or get feedback on proposed improvements. 31 | 32 | ### Example documentation bugs 33 | 34 | Here are a couple of successfully resolved bugs as examples. 35 | 36 | 1. [Bug 16003 - heatmap scale argument: description not complete](https://bugs.r-project.org/show_bug.cgi?id=16003) 37 | 38 | There was a question about the description in the documentation, where it wasn't technically incorrect, but was slightly unclear. This led to a discussion around the updates to the text and a couple of extra examples were added in for clarity too. 39 | 40 | 2. [Bug 18781 - typo in texinfo](https://bugs.r-project.org/show_bug.cgi?id=18781) 41 | 42 | This is an example of a typo being spotted, raised and fixed within the same day. 43 | 44 | ## Guidelines for writing R help files 45 | 46 | This section is based on the [guidelines used by R Core developers for writing R help files](https://developer.r-project.org/Rds.html). Extensive details of writing R documentation files can be found in the [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) manual. 47 | 48 | The language used in the documentations should follow these basic rules: 49 | 50 | 1. Affirmative tone should be used to describe what the function does and how to use it effectively. Rather than creating worry in the mind of a reader, it should establish confident knowledge about the effective use of the particular function/feature. 51 | 52 | 2. More documentation is not necessarily better documentation. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is. Be succinct but exhaustive. 53 | 54 | 3. Short code examples can help in understanding better. Readers can often grasp a simple example more quickly than they can digest a formal description. Usually people learn faster with concrete, motivating examples that match the context of a typical use case. 55 | 56 | 4. Giving a code equivalent (or approximate equivalent) can be a useful addition to the description provided. You should carefully weigh whether the code equivalent adds value to the document. 57 | 58 | 5. The tone of the documentation needs to be respectful of the reader's background. Lay out the relevant information, show motivating use cases, provide glossary links, and do your best to connect-the-dots. The documentation is meant for newcomers, many of whom will be using it to evaluate the R language as a whole. The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a mistake. 59 | 60 | ## Introduction to `.Rd` files 61 | 62 | The R help files are written in “R documentation” (Rd) format, a markup language which resembles LaTeX. The `.Rd` file format can be further processed into a variety of formats, including LaTeX, HTML, and plain text. The `.Rd` files can be found in the `man` directory of the source code for the corresponding package. 63 | 64 | There are three main parts of an `.Rd` file: 65 | 66 | 1. **Header**: This part is for the basic information of the document/file. For instance, the name of the file, the topics documented, a title, a short textual description, and R usage information for the objects documented. 67 | 68 | 2. **Body**: This part includes further information on the function's arguments and return value. 69 | 70 | 3. **Footer**: This part is optional. Usually the keyword information is included here. 71 | 72 | All the above information is included in a `.Rd` file within a series of sections with standard names (user-defined sections are also allowed). These sections are discussed below: 73 | 74 | 1. `\title` section: 75 | * Capitalize each word. 76 | * Do not end in a period. 77 | * Avoid use of markup language (because markup language need not be suitable for various hypertext search systems). 78 | 79 | 2. `\usage` and `\examples` sections: 80 | * Line length of 65 characters is advised. 81 | * Use `TRUE` instead of `T` and `FALSE` instead of `F`. 82 | * Add spaces around binary operators. 83 | * Add spaces after commas in the argument lists. 84 | * Use `<-` rather than `=` for assignments. 85 | * Add spaces around the `<-` operator. 86 | * Do not use tabs to indent (as these do not render correctly on all possible pagers). 87 | * Use 4 spaces to indent the (example) code. 88 | * Make sure the examples are directly executable. 89 | * The examples should be system-independent. 90 | * The examples should not require special facilities (for instance, Internet access or write permission to specific directories). 91 | * Examples should also not take longer than necessary to run, as they are run when checking a build of R. 92 | 93 | 3. `\source` and `\references` sections: 94 | * Author(s) names should be written in the form `Author, A. B.`. 95 | * Author(s) names should be separated by a comma or `and` (but not both). 96 | * Separate paragraphs (separated by a blank line) should be used for each reference. 97 | * Give a date immediately after the author(s) names. 98 | * Do not put a period after the date. 99 | * Titles of books and journals (not articles) should be enclosed in `\emph{...}`. 100 | * Volume numbers for journals are to be enclosed in `\bold{...}` and followed by a comma. 101 | * Use `--` for page ranges. 102 | * For giving an address for a publisher use the format `New York: Springer-Verlag`. 103 | 104 | For example, the help file for `base::mean()` is found at . The file`mean.Rd` has the content shown below: 105 | 106 | ``` 107 | % File src/library/base/man/mean.Rd 108 | % Part of the R package, https://www.R-project.org 109 | % Copyright 1995-2022 R Core Team 110 | % Distributed under GPL 2 or later 111 | 112 | \name{mean} 113 | \title{Arithmetic Mean} 114 | \usage{ 115 | mean(x, \dots) 116 | 117 | \method{mean}{default}(x, trim = 0, na.rm = FALSE, \dots) 118 | } 119 | \alias{mean} 120 | \alias{mean.default} 121 | \arguments{ 122 | \item{x}{An \R object. Currently there are methods for 123 | numeric/logical vectors and \link[=Dates]{date}, 124 | \link{date-time} and \link{time interval} objects. Complex vectors 125 | are allowed for \code{trim = 0}, only.} 126 | \item{trim}{the fraction (0 to 0.5) of observations to be 127 | trimmed from each end of \code{x} before the mean is computed. 128 | Values of trim outside that range are taken as the nearest endpoint. 129 | } 130 | \item{na.rm}{a logical evaluating to \code{TRUE} or \code{FALSE} 131 | indicating whether \code{NA} values should be stripped before the 132 | computation proceeds.} 133 | \item{\dots}{further arguments passed to or from other methods.} 134 | } 135 | \description{ 136 | Generic function for the (trimmed) arithmetic mean. 137 | } 138 | \value{ 139 | If \code{trim} is zero (the default), the arithmetic mean of the 140 | values in \code{x} is computed, as a numeric or complex vector of 141 | length one. If \code{x} is not logical (coerced to numeric), numeric 142 | (including integer) or complex, \code{NA_real_} is returned, with a warning. 143 | 144 | If \code{trim} is non-zero, a symmetrically trimmed mean is computed 145 | with a fraction of \code{trim} observations deleted from each end 146 | before the mean is computed. 147 | } 148 | \references{ 149 | Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) 150 | \emph{The New S Language}. 151 | Wadsworth & Brooks/Cole. 152 | } 153 | \seealso{ 154 | \code{\link{weighted.mean}}, \code{\link{mean.POSIXct}}, 155 | \code{\link{colMeans}} for row and column means. 156 | } 157 | \examples{ 158 | x <- c(0:10, 50) 159 | xm <- mean(x) 160 | c(xm, mean(x, trim = 0.10)) 161 | } 162 | \keyword{univar} 163 | ``` 164 | 165 | Many R package developers write help files using the R package [roxygen2](https://cran.r-project.org/package=roxygen2), which generates `.Rd` files from comments in the corresponding `.R` files. However, in this guide we only consider `.Rd` files, because the help files for the base distribution are written and edited directly in `.Rd` format. 166 | 167 | ## R manuals 168 | 169 | The [R manuals](https://cran.r-project.org/manuals.html) are a part of the [R sources](https://svn.r-project.org/R/trunk/doc/manual/). Hence, bug reports/patches can also be submitted via Bugzilla, e.g. [Bug 15221 - R-admin/'Installing R under Windows': Missing argument name](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=15221). Note that they are typically referred to by their file names as listed below: 170 | 171 | | Manual | Nickname | 172 | | -- | -- | 173 | | An Introduction to R | "R-intro" | 174 | | R Data Import/Export | "R-data" | 175 | | R Installation and Administration | "R-admin" | 176 | | Writing R Extensions | "R-exts" | 177 | | The R language definition | "R-lang" | 178 | | R Internals | "R-ints" | 179 | 180 | 181 | :::{.callout-note} 182 | - Every manual is associated with a particular version of R, so you should check the version before reporting a bug. 183 | - The [R manuals](https://cran.r-project.org/manuals.html) page has links for the [three types of release](getting_started.qmd#the-r-source-code): `r-release`, `r-patched` and `r-devel`. These nicknames appear in the URLs, e.g. https://cran.r-project.org/doc/manuals/r-release/R-intro.html. 184 | - The [Texinfo manual](https://www.gnu.org/software/texinfo/) should be referred to for [how to mark up text](https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html). 185 | ::: 186 | 187 | ## Proofreading 188 | 189 | While an issue filed on Bugzilla means there is a known issue somewhere, that does not mean there are not other issues lurking about in the documentation. Proofreading a part of the documentation can often uncover problems. 190 | 191 | If you decide to proofread, read a section of the documentation from start to finish, filing issues in Bugzilla for each major type of problem you find. It is best to avoid filing a single issue for an entire section containing multiple problems; instead, file several issues so that it is easier to break the work up for multiple people and more efficient review. 192 | 193 | ## Helping with the R Development Guide 194 | 195 | The R Development Guide (what you are reading now) uses the same process as the main R documentation, except for some small differences. The source lives in a [GitHub repository](https://github.com/r-devel/rdevguide/) and bug reports should be submitted to the [devguide GitHub tracker](https://github.com/r-devel/rdevguide/issues). 196 | 197 | There's a section on the introduction page detailing [how to contribute to this guide](#how-to-contribute-to-this-guide). Once you have made suggested changes you can raise them for someone else to review through a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) on GitHub. Examples of past pull requests can be found on the [pull request tab in this guide's GitHub repository](https://github.com/r-devel/rdevguide/pulls?q=is%3Apr+is%3Aclosed). 198 | Our workflow for the R Development Guide uses continuous integration and deployment so changes to the live R Development Guide site are normally published once a pull request is merged. 199 | 200 | ## See also 201 | 202 | 1. [Writing R documentation files](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-R-documentation-files) 203 | -------------------------------------------------------------------------------- /chapters/finding_the_source.qmd: -------------------------------------------------------------------------------- 1 | # Finding the Source {#FindSource} 2 | 3 | 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. 4 | 5 | ## Finding R source code 6 | 7 | 1. Find the R function with the code of interest. You will always be able to print the top-level function (or use `View(function_name)` in RStudio). Looking at the code for the body of this function will reveal what you need to do next: 8 | 9 | * Can already see code of interest: stop here or skip to step 3 to find the corresponding file in the R sources. 10 | 11 | * Code of interest is in nested R function: go to step 2. 12 | 13 | * Top-level function is an S3 generic, identified by a call to `UseMethod()`. Use `methods(function_name)` to see available methods, then go to step 2. 14 | 15 | * Code of interest is in compiled code, identified by a call to `.C()`, `.Call()`, `.Fortran()`, `.External()`, and `.External.graphics()`, or `.Internal()` and `.Primitive()`: go to section on compiled code. 16 | 17 | 2. 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 `getAnywhere()` or `getS3method()`. Now you can keep looking at nested R functions till you find the code of interest or hit a call to compiled code. 18 | 19 | 3. Find an R function in the R sources. Two options here: 20 | 21 | * Search on the internet: For R Core packages, search on the GitHub mirror (https://github.com/r-devel/r-svn); for recommended packages, use the CRAN mirror (https://github.com/cran) - this will link to the source on GitHub if available, e.g. https://github.com/cran/survival. Note that GitHub search ignores wildcard characters 22 | 23 | ``` 24 | . , : ; / \ ` ' " = * ! ? # $ & + ^ | ~ < > ( ) { } [ ] 25 | ``` 26 | 27 | but this does not include `-` so you can search for a function or S3 method as follows: 28 | 29 | ``` 30 | "body <- function" extension:R 31 | "quantile.ecdf <- function" extension:R 32 | ``` 33 | 34 | * Search in the R sources using grep: The [R Patched and Development Versions](#GetStart) chapter discusses how to download the R sources directly or from the svn repository. Now if the sources are in `~/R-devel`, you can search as follows: 35 | 36 | ``` 37 | grep -R "body <- function" ~/R-devel/src 38 | grep -R "quantile <- function" ~/R-devel/src/library 39 | ``` 40 | 41 | Note: The above procedure does not cover S4, R6 or RC generics or methods. Refer [accessing R source](https://github.com/jennybc/access-r-source) for further details. 42 | 43 | ## Finding C source code 44 | 45 | 1. If `.Internal()` or `.Primitive()`, find entry point in `names.c` as described in the Jenny Bryan's post of [accessing R source](https://github.com/jennybc/access-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 46 | 47 | ``` 48 | .External(C_compcases, ...) 49 | ``` 50 | 51 | `C_compcases` inherits from class "NativeSymbolInfo" and we can extract the name of the entry point via 52 | 53 | ``` 54 | stats:::C_compcases$name 55 | ``` 56 | 57 | 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 `C_` prefix (sometimes `.F_` for Fortran code^[Other variations are also possible. For example, `.External.graphics()` calls to C functions in the grid package have a `C_` prefix in the R code, but an `L_` prefix in the C code.]) in the name of the object passed to the first argument of the call. 58 | 59 | 2. Once you have the entry point, search as for R code. In the case of searching on GitHub, restrict the search to files with the relevant extension 60 | 61 | ``` 62 | compcases path:*.c 63 | lowesw path:*.f 64 | ``` 65 | 66 | similarly for grep 67 | 68 | ``` 69 | grep -R --include=*.c "compcases" ~/R-devel/src/library/ 70 | ``` 71 | 72 | Note: 73 | 74 | 1. Many editors (like RStudio, ESS) support [ctags](https://en.wikipedia.org/wiki/Ctags) for code browsing, making it easy to jump to definitions of functions. `R CMD rtags` can generate ctags for any R code (Credit: Deepayan Sarkar). 75 | 76 | 2. A more sophisticated system is called GNU GLOBAL, which also supports 77 | finding all references (calls) to a function. 78 | 79 | 3. GitHub has a code navigation feature via the library tree-sitter. Unfortunately, it does not have R support yet. An [R driver for tree-sitter](https://github.com/r-lib/tree-sitter-r) made by Jim Hester is available. 80 | 81 | ## See also 82 | 83 | [Read the R source](https://blog.r-hub.io/2019/05/14/read-the-source/) blogpost. 84 | -------------------------------------------------------------------------------- /chapters/getting_started.qmd: -------------------------------------------------------------------------------- 1 | # R Patched and Development Versions {#GetStart} 2 | 3 | These instructions cover how to install R from source or from binaries. 4 | Contributors will typically need to work with the patched or development versions of R. 5 | 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). 6 | The tools required to build R and R packages are also discussed. 7 | For the most up to date and complete instructions you can check the [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html) . 8 | 9 | ## The R source code 10 | 11 | R uses [svn](https://subversion.apache.org/ "SVN official page") as a version control tool hosted at and uses a 'major.minor.patchlevel' version numbering scheme[^02-getting_started-1]. 12 | 13 | [^02-getting_started-1]: Also known as [semantic versioning](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning "Wikipedia explanation of semantic versioning") 14 | 15 | There are three releases of R available to install: 16 | 17 | - The latest official release (`r-release`), either major version x.0.0 or minor version x.y.0, for example: 3.0.0 or 3.2.0 18 | 19 | - The patched release (`r-patched`), for example 3.0.1 or 3.2.1 and 20 | 21 | - The development release (`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"). 22 | 23 | The source code of released versions of R can be found at [R/tags](https://svn.r-project.org/R/tags/ "svn release source code folder"), the patched versions are at [R/branch](https://svn.r-project.org/R/branches/ "svn patched source code folder"). 24 | 25 | 26 | The `r-devel` at [R/trunk](https://svn.r-project.org/R/trunk "svn devel source code folder") is the next minor or eventual major release development version of R. 27 | Bug fixes and new features are introduced in `r-devel` first. 28 | If the change meets the [development guidelines](https://developer.r-project.org/devel-guidelines.txt) R Core will also make the change in `r-patched`. 29 | 30 | ## Prerequisites 31 | 32 | To install from the source code you will need the source code and the dependencies of R. 33 | 34 | If you need to install svn you can use your distribution's package manager to install it. 35 | 36 | ### Ubuntu 37 | 38 | In Ubuntu you can use this command to find all the dependencies of R: 39 | 40 | ```sh 41 | apt-rdepends --build-depends --follow=DEPENDS r-base-dev | grep " B" | sed -e "s/ Build-Depends: //" 42 | ``` 43 | 44 | It might require installation of apt-rdepends which can be done from default repositories via `sudo apt-get install apt-rdepends`. 45 | 46 | To install all the R dependencies you can use: 47 | 48 | ```sh 49 | sudo apt-get build-dep r-base-dev 50 | ``` 51 | 52 | ### Fedora 53 | 54 | In Fedora you can use this command to find all the dependencies of R: 55 | 56 | ```sh 57 | dnf rq -q --repo=fedora-source --requires R 58 | ``` 59 | 60 | You will also need the rsync package to download the recommended packages. 61 | 62 | To install them you can use: 63 | 64 | ```sh 65 | dnf install 'dnf-command(builddep)' 66 | dnf install rsync 67 | dnf builddep R 68 | ``` 69 | 70 | 71 | ## Building R 72 | 73 | It is recommended to build R in a different path than the source. 74 | For this reason we have a `TOP_SRCDIR` variable where the source code goes and the variable `BUILDDIR` where the built R version will go. 75 | 76 | ### Linux 77 | 78 | Here are the basic steps intended as a checklist. 79 | For complete instructions please see the section in [R-admin](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#Installing-R-under-Unix_002dalikes). 80 | 81 | 0. Retrieve R source code via into `TOP_SRCDIR`, note that we retrieve the `r-devel` source code: 82 | 83 | ```sh 84 | export TOP_SRCDIR="$HOME/Downloads/R" 85 | svn checkout https://svn.r-project.org/R/trunk/ "$TOP_SRCDIR" 86 | ``` 87 | 88 | 1. Download the latest recommended packages[^02-getting_started-2]: 89 | 90 | ```sh 91 | "$TOP_SRCDIR/tools/rsync-recommended" 92 | ``` 93 | 94 | 3. Create the build directory in the `BUILDDIR`: 95 | 96 | ```sh 97 | export BUILDDIR="$HOME/bin/R" 98 | mkdir -p "$BUILDDIR" 99 | cd "$BUILDDIR" 100 | ``` 101 | 102 | 4. Configure the R installation (with `--enable-R-shlib` so that RStudio IDE can use it): 103 | 104 | ```sh 105 | "$TOP_SRCDIR/configure" --enable-R-shlib 106 | ``` 107 | 108 | 4. Build R : 109 | 110 | ```sh 111 | make 112 | ``` 113 | 114 | 115 | 5. Check that R works as expected: 116 | 117 | ```sh 118 | make check 119 | ``` 120 | 121 | There are other checks you can run: 122 | 123 | ```sh 124 | make check-devel 125 | make check-recommended 126 | ``` 127 | 128 | 129 | [^02-getting_started-2]: Recommended packages are not in the subversion repository. 130 | 131 | 132 | If we don't want to build R in a different directory than the source code we can simply use: 133 | 134 | ```sh 135 | cd "$TOP_SRCDIR" 136 | svn update 137 | tools/rsync-recommended 138 | "$TOP_SRCDIR/configure" --enable-R-shlib 139 | make 140 | make check 141 | ``` 142 | 143 | Once you successfully built R from source you can modify the R source code to fix an issue: Prepare a patch (See [this guide](https://www.r-project.org/bugs.html#how-to-submit-patches)) and after checking that R works as intended (`make check-devel`) submit the patch for consideration by R Core. 144 | (See the [lifecycle of a patch](#FixBug) chapter). 145 | 146 | 147 | To use the `r-devel` version in RStudio, you can do the following: 148 | 149 | ```sh 150 | export RSTUDIO_WHICH_R="$BUILDDIR/bin/R" 151 | cd "$TOP_SRCDIR" 152 | rstudio 153 | ``` 154 | 155 | 156 | ### Windows 157 | 158 | #### Binaries 159 | 160 | The binary builds of R for Windows can be downloaded and installed from [here](https://cran.r-project.org/bin/windows/base/). 161 | Along with the link to the latest stable release, this page also contains links to the binary builds of `r-patched` and `r-devel`. 162 | 163 | 1. Click on the download links to download an executable installer. 164 | 165 | 2. Select the language while installing, read the GNU general public license information, and select the destination location to start the installation. 166 | You will be prompted to select components at this stage: `User installation`, `64-bit User installation`, or `Custom installation`. 167 | The default option may be chosen for the questions from this step onwards to complete the installation. 168 | 169 | Daily binaries for `r-devel` are made available for [download and installation](https://cran.r-project.org/bin/windows/base/rdevel.html). 170 | 171 | #### From source {#windowsSource} 172 | 173 | Before installing R from source, some additional programs are needed, as per the [latest documentation](https://cran.r-project.org/bin/windows/base/howto-R-4.2.html): 174 | 175 | 1. [Rtools](https://cran.r-project.org/bin/windows/Rtools/) is the suggested toolchain bundle for building R base and R packages containing compiled code on Windows. 176 | The latest [version of Rtools](https://cran.r-project.org/bin/windows/Rtools/rtools44/rtools.html) can be installed using the [Rtools installer rtools44-XXXX-XXX.exe ](https://cran.r-project.org/bin/windows/Rtools/rtools44/files/). 177 | 178 | 2. A LaTeX compiler is needed to install and build R, check packages and build manuals. 179 | On CRAN, MiKTeX is used, which can be downloaded from . 180 | Once installed open MiKTeX via the Windows start menu. 181 | It might ask to check for updates and more importantly, to make it available in PATH. You can accept both. 182 | 183 | 1. Open the Rtools44 terminal to update and install subversion: 184 | 185 | ```sh 186 | pacman -Syuu 187 | pacman -Sy wget subversion 188 | ``` 189 | 190 | 3. Retrieve the latest source code via subversion: 191 | 192 | ```sh 193 | export TOP_SRCDIR="$HOME/Downloads/R" 194 | svn checkout https://svn.r-project.org/R/trunk/ "$TOP_SRCDIR" 195 | ``` 196 | 197 | If you already have the repository available you can update as: 198 | 199 | ```sh 200 | cd $TOP_SRCDIR 201 | svn update 202 | ``` 203 | 204 | You can also use a SVN client such as TortoiseSVN (, command line tool, and Windows Explorer integration) or SlikSVN (, just the command line tool) so that it can be also found by other tools. 205 | 206 | 2. Download the latest tcl/tk and unzip it in `$TOP_SRCDIR`: 207 | 208 | ```sh 209 | cd "$TOP_SRCDIR" 210 | wget -np -nd -r -l1 -A 'tcltk-*.zip' https://cran.r-project.org/bin/windows/Rtools/rtools44/files/ 211 | unzip "tcltk-*.zip" 212 | ``` 213 | 214 | 3. Add gcc, MiKTeX and tar to the PATH and set one tar option: 215 | 216 | ```sh 217 | export PATH="/x86_64-w64-mingw32.static.posix/bin:$PATH" 218 | export PATH="/c/Program Files/MiKTeX/miktex/bin/x64:$PATH" 219 | export TAR="/usr/bin/tar" 220 | export TAR_OPTIONS="--force-local" 221 | ``` 222 | 223 | If MiKTeX was installed just for your user you might need to run: 224 | 225 | ```sh 226 | export PATH="/c/Users/$USER/AppData/Local/Programs/MiKTeX/miktex/bin/x64:$PATH" 227 | ``` 228 | 229 | 4. Check that all the programs can be found: 230 | 231 | ```sh 232 | which make gcc pdflatex tar 233 | ``` 234 | 235 | If there is any error you'll need to find where the program is installed and add the corresponding path. 236 | 237 | 5. Download the latest recommended packages[^02-getting_started-2]: 238 | 239 | ```sh 240 | cd "$TOP_SRCDIR/src/gnuwin32/" 241 | "$TOP_SRCDIR/tools/rsync-recommended" 242 | ``` 243 | 244 | 6. Build R and the recommended packages: 245 | 246 | ```sh 247 | make all recommended 248 | ``` 249 | 250 | The recently compiled version of R will be at `$TOP_SRCDIR/bin/`. 251 | In RStudio you can select that folder and restart it to use the `r-devel` version. 252 | 253 | 7. Check that R works as expected: 254 | 255 | ```sh 256 | make check 257 | ``` 258 | 259 | There are other checks you can run for testing the successful installation of the recommended packages: 260 | 261 | ```sh 262 | make check-devel 263 | make check-recommended 264 | ``` 265 | 266 | 267 | ### macOS 268 | 269 | This section will be added after the official [installation instructions for macOS in the R installation and administration manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#macOS) have been updated for R 4.4.0. 270 | 271 | 272 | ## See also 273 | 274 | 1. [CRAN official website](https://cran.r-project.org) 275 | 276 | 2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html) 277 | 278 | 3. [R for macOS](https://mac.r-project.org/) 279 | 280 | 3. [Tools for R in macOS](https://mac.r-project.org/tools/) 281 | 282 | 3. [R for requirements in macOS](https://mac.r-project.org/src/) 283 | 284 | 3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) 285 | 286 | 4. [RTools toolchains for Windows](https://cran.r-project.org/bin/windows/Rtools/) 287 | 288 | 5. [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html) 289 | -------------------------------------------------------------------------------- /chapters/introduction.qmd: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | This guide is a comprehensive resource for contributing to base R^[The [set of packages](https://cran.r-project.org/doc/FAQ/R-FAQ.html#Add_002don-packages-in-R) in the base R distribution that are maintained by the R Core Team.] – for both new and experienced contributors. It is maintained by the [R Contribution Working Group](/working-group). We welcome your contributions to base R! 4 | 5 | ## Overview of different ways of contributing to the base R Project 6 | 7 | Contributions to base R are possible in a number of different ways. Some of them are listed below: 8 | 9 | 1. Contributing to bug fixing: Refer to [Issue Tracking](#IssueTrack) and [Reviewing Bugs](#ReviewBugs). 10 | 2. Contributing to translations: Refer to [Translations](#message-translations). 11 | 3. Testing R before release: Refer to [Testing Pre-release R Versions](#TestRVer). 12 | 4. Contributing to documentation, including this guide: Refer to [Documenting R](#Doc) and [Contributing to this guide](#how-to-contribute-to-this-guide). 13 | 14 | 15 | 16 | 17 | ## Quick start to the guide 18 | 19 | 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. 20 | 21 | - The [Introduction](#Introduction) chapter provides an overview of different ways of contributing to the R project, a quick start to the guide, and a section on how to contribute to the guide itself. 22 | 23 | - The [R Patched and Development Versions](#GetStart) chapter covers instructions on how to install R from source or from binaries and also discusses the tools required to build R. 24 | 25 | - The [Issue Tracking](#IssueTrack) chapter covers how contributors can support issue tracking in R, how to get an account on R's Bugzilla, how to navigate Bugzilla and search for bugs to contribute to. 26 | 27 | - The [Reporting Bugs](#ReportingBugs) chapter discusses what condition may or may not be a bug and how to report bugs if you find them. 28 | 29 | - The [Submitting Feature Requests](#FeatureRequests) chapter discusses how to submit feature requests and shares some examples submitted to Bugzilla. 30 | 31 | - The [Reviewing Bugs](#ReviewBugs) chapter discusses how you can make a contribution to reviewing bug reports. 32 | 33 | - The [Finding the Source](#FindSource) chapter provides an overview of the R codebase and helps with finding source code of base functions written in R and/or C. 34 | 35 | - The [Lifecycle of a Patch](#FixBug) chapter discusses how to create a patch to propose a bug fix. 36 | 37 | - The [Documenting](#Doc) 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. 38 | 39 | - The [Message Translations](#MessageTranslations) chapter covers internationalization in R, i.e., the display of messages in languages other than English. 40 | 41 | - The [Testing Pre-release R Versions](#TestRVer) chapter discusses how you can help with testing of pre-release versions of R. 42 | 43 | - For more information on how to engage with the community and ask for help, refer to the [Where to Get Help](#WhereToGetHelp) chapter. 44 | 45 | - To keep up with the developments in R refer to the resources available in the [News and Announcements](#News) chapter. 46 | 47 | - Tools that may be useful for R developers are available in the [Developer Tools](#DevTools) chapter. 48 | 49 | - Additional resources for contributing to R are available in the [Additional Resources](#AdditionalResources) chapter. 50 | 51 | - The [R Core Developers](#CoreDev) chapter contains a list of the former and current members of the R Core Team who have write access to the R source. 52 | 53 | ## How to contribute to this guide itself? {#how-to-contribute-to-this-guide} 54 | 55 | All contributors should start by reading the [contributing page for this project](https://github.com/r-devel/rdevguide/blob/main/CONTRIBUTING.md). 56 | 57 | Maintainers and contributors are also requested to follow [this guide's code of conduct](https://github.com/r-devel/rdevguide/blob/main/CONDUCT.md). 58 | 59 | This guide is built using Quarto which makes editing it easier, provided you have a GitHub account (sign-up at [github.com](https://github.com/)). After you log-in to GitHub, click on the ‘Edit this page’ (available in the left side column) link 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: 60 | 61 | ![Screenshot of the toolbar in the HTML version of the guide, with the "Edit this page" link highlighted in red.](../img/edit_icon.png) 62 | 63 | Use the [issue tracker](https://github.com/r-devel/rdevguide/issues) to raise an issue about the guide’s content or to make a feature request. 64 | -------------------------------------------------------------------------------- /chapters/issue_tracking.qmd: -------------------------------------------------------------------------------- 1 | # Issue Tracking {#IssueTrack} 2 | 3 | Base R uses [Bugzilla](https://bugs.r-project.org/) for issue tracking and reporting bugs. 4 | 5 | ## How to contribute to issue tracking? 6 | 7 | Contributors can support issue tracking in R by 8 | 9 | 1. [Reporting bugs](#ReportingBugs) or [submitting feature requests](#FeatureRequests) (bug reports filed under the "Wishlist" component in Bugzilla), 10 | 11 | 2. [Reviewing bug reports](reviewing_bugs.qmd) to help close reports where no fix is needed or to help narrow down the problem and identify what needs to be fixed, or 12 | 13 | 3. [Proposing changes](lifecycle_of_a_patch.qmd) to code or documentation that will close an issue. 14 | 15 | ## How to get a Bugzilla account? {#bugzilla-account} 16 | 17 | 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. 18 | 19 | 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. After having successfully logged in to Bugzilla, you are good to go. 20 | 21 | ### Navigating Bugzilla {#Bugzilla} 22 | 23 | An image of the existing home page of Bugzilla is shared below: 24 | 25 | ![Screenshot of the existing home page of Bugzilla.](../img/bugzilla.png) 26 | 27 | On the home page of Bugzilla, there are various buttons and links. There are four square buttons called as: 28 | 29 | ![Screenshot of the four square buttons on the home page of Bugzilla.](../img/squarebuttons.png) 30 | 31 | 1. [File a bug](https://bugs.r-project.org/enter_bug.cgi): You will have to log in to Bugzilla to file a bug using this button 32 | 33 | 2. [Search](https://bugs.r-project.org/query.cgi): 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. 34 | 35 | 3. [Log In](https://bugs.r-project.org/?GoAheadAndLogIn=1): Provide the appropriate email address and password here to log in to Bugzilla. 36 | 37 | 4. [Documentation](https://bugzilla.readthedocs.io/en/latest/using/index.html): Provides a user guide for R\'s Bugzilla. 38 | 39 | Several useful shortcuts are available from the landing page: 40 | 41 | 1. [Enter a new bug report](https://bugs.r-project.org/enter_bug.cgi) 42 | 43 | 2. [Show open bugs new-to-old](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) 44 | 45 | 3. [Search existing bug reports](https://bugs.r-project.org/query.cgi) 46 | 47 | A [quick search](https://bugs.r-project.org/page.cgi?id=quicksearch.html) bar is available on the home page where you can enter a bug number to search or some search terms. 48 | 49 | ![Screenshot of the quick search bar on the home page of Bugzilla.](../img/quicksearch.png) 50 | 51 | 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. 52 | 53 | ![Screenshot of the Common Queries section on the home page of Bugzilla.](../img/commonquery.png) 54 | 55 | ## Searching for Bugs to Contribute to {#searching} 56 | 57 | When presented with a long list of bugs, it can often be a bit demotivating when it's not clear where to start. 58 | To help with this, you can use the [**Advanced Search**](https://bugs.r-project.org/query.cgi?format=advanced). 59 | 60 | ![Screenshot of Advanced Search page showing the following fields: Summary, Product, Component, Status, Resolution](../img/bugzilla-adv-search-home.png) 61 | 62 | This presents several fields that you can use to narrow down your search. 63 | You can find out what a particular field is by clicking on the header, which will take you to that section in the [**Bug Fields Information Page**](https://bugs.r-project.org/page.cgi?id=fields.html). 64 | 65 | The default fields are: 66 | 67 | - [Summary](https://bugs.r-project.org/page.cgi?id=fields.html#short_desc): a short description of the bug 68 | - [Product](https://bugs.r-project.org/page.cgi?id=fields.html#product): either R or RTools. 69 | - [Component](https://bugs.r-project.org/page.cgi?id=fields.html#component): A specific component of the R toolchain such as Graphics, Documentation, and Models 70 | - [Status](https://bugs.r-project.org/page.cgi?id=fields.html#bug_status): The status of open or closed bugs. This will always default to showing open bugs (UNCONFIRMED, CONFIRMED, and IN_PROGRESS) 71 | - [Resolution](https://bugs.r-project.org/page.cgi?id=fields.html#resolution): The resolution for closed bugs. 72 | 73 | You can select multiple items for each field as well. 74 | Both **Product** and **Component** are what you navigate through when you go to [**Browse Issues**](https://bugs.r-project.org/describecomponents.cgi). 75 | 76 | Below that are further filters that can help you find bugs you might want to work on: 77 | 78 | Detailed Bug Information: Narrow results by the following fields 79 | : Comments, URL, Keywords, Deadline, Bug Numbers, Version, Severity, Priority, Hardware, OS 80 | Search By People 81 | : Narrow results to a role (i.e. Assignee, Reporter, Commenter, etc.) a person has on a bug 82 | Search By Change History 83 | : Narrow results to how fields have changed during a specific time period 84 | Custom Search 85 | : Didn't find what you're looking for above? This area allows for ANDs, ORs, and other more complex searches. 86 | 87 | These will be detailed in the subsections below 88 | 89 | 90 | ### Detailed Bug Information {#searching-dbi} 91 | 92 | You can use this section to narrow down your search further to filter by things like OS type, R version, Keywords, and Priority. 93 | 94 | It can be helpful, for example, to search for bugs labelled with `HELPWANTED`, which indicates bugs that may be suitable for anyone to work on regardless of expertise. 95 | 96 | ![Screenshot of expanded Detailed Bug Information section showing the following fields: Comment, URL, Keywords (with HELPWANTED entered), Deadline, inclusion/exclusion of bug numbers, Version, Severity, Priority, Hardware, and OS](../img/bugzilla-adv-search-detailed-bug-info.png) 97 | 98 | 99 | ### Search By People {#searching-sbp} 100 | 101 | You can use this to narrow down your search to only include results of a specific person or up to three people who have participated in any component of the bug's discussion. 102 | 103 | ![Screenshot of expanded Search By People section showing three fields allowing you to enter a person's name who can be any of the bug assignee, the reporter, a CC list member, or a commenter](../img/bugzilla-adv-search-search-by-people.png) 104 | 105 | 106 | ### Search By Change History {#searching-sbch} 107 | 108 | Use this to search for bugs where any of the status fields has been changed (which, depending on the change, could indicate that someone from R-Core has given some attention to the bug). 109 | This also provides a date range to narrow your search. 110 | 111 | ![Screenshot of expanded Search by Change History section showing three fields: where ANY of the fields (multi-select list), changed to, and between (dates in YYYY-MM-DD format)](../img/bugzilla-adv-search-search-by-change-history.png) 112 | -------------------------------------------------------------------------------- /chapters/lifecycle_of_a_patch.qmd: -------------------------------------------------------------------------------- 1 | # Lifecycle of a Patch {#FixBug} 2 | 3 | ## Introduction 4 | 5 | R uses a workflow based on patches. A patch is the set of differences (additions and deletions) between two versions of code. So you can create a patch defining a bug fix or a proposed update to the R codebase and submit it through your official Bugzilla account to the core developer(s). Be clear in your communication as it is the key to contributing to any project, especially an open source project like R. 6 | 7 | ## When do you submit a patch? 8 | 9 | There might be a situation where you come across a bug in R, which you may have an idea of how to fix. This can turn out to be an opportunity for you to submit a patch. By submitting a patch or a bug fix, you are helping to reduce the workload on the R developers in addition to yourself being a contributor to R! 10 | 11 | When you submit a patch, you are helping the developer(s) and maintainer(s) so that they do not have to write the entire code from scratch. Instead, they can test and tweak your patch, if necessary. 12 | 13 | ## What tools are required to submit a patch? 14 | 15 | To submit a patch, you need: 16 | 17 | 1. [SVN](http://subversion.apache.org/) installed on your machine. 18 | 19 | 2. The latest developer version of R. 20 | 21 | You can retrieve the latest source code of R via: 22 | 23 | ```sh 24 | export TOP_SRCDIR="$HOME/Downloads/R" 25 | svn checkout https://svn.r-project.org/R/trunk/ "$TOP_SRCDIR" 26 | ``` 27 | 28 | Depending on the operative system you might need to do some steps before that. 29 | The different steps required can be found in previous chapters of the book, for [Windows](#windowsSource), [macOS](#macos) and [Linux](#linux). 30 | 31 | ## How to prepare a patch? 32 | 33 | 34 | If you have the source code in `$TOP_SRCDIR` you can edit the files, for example a documentation file such as `"$TOP_SRCDIR"/src/library/stats/man/Multinom.Rd`, to make your desired changes to that or more files. 35 | 36 | Then you should check that R still works as expected via: 37 | 38 | ```sh 39 | cd "$TOP_SRCDIR" 40 | make check-devel 41 | ``` 42 | 43 | If there is no test for your proposed change you can add a new regression test, following [the guidelines](#TestRVer). 44 | 45 | Then you should bring changes from the repository into the working copy, in case any other change has been introduced, and create a patch.diff file with just the changes you want to propose to the R core: 46 | 47 | ```sh 48 | svn update 49 | svn diff > patch.diff 50 | ``` 51 | 52 | Most often, changes are made to existing files, but if you happen to be adding a new file in your change, you'll need to run `svn add path/to/file1 ...` before running `svn diff` to mark those files for inclusion. 53 | 54 | This `patch.diff` file is the one that can be proposed to the R core via [Bugzilla](#SubmitPatches). You can also [ask for reviews](#PatchesReview) to the patch before proposing it to the R core via the [r-devel mailing list](https://stat.ethz.ch/mailman/listinfo/r-devel) or the slack channel of the R-contributors space. 55 | 56 | ### Using a git mirror 57 | 58 | Besides checking in your computer, you can use the Github mirror [r-devel/r-svn](https://github.com/r-devel/r-svn "A github svn mirror") of the source code to check this patch with different configurations and OS. 59 | 60 | You should first find the file to edit, via the github interface for example: 61 | 62 | ![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](../img/rsvn_file_to_edit.png "Opening the file to edit.") 63 | 64 | Then you can edit it, directly in the interface or using the github interface: 65 | 66 | ![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](../img/rsvn_edit_file.png "Editing a file via Github interface.") 67 | 68 | Create a commit with a message describing the changes 69 | 70 | ![Screenshot of the commit message](../img/rsvn_commit_message.png "Commiting the change in the file.") 71 | 72 | And create a pull request from the branch created to check the changes. 73 | 74 | ![Screenshot of the message when opening a pull requests from the branch](../img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.") 75 | 76 | Add a message and description of the svn for other users and the R core to know what is the purpose of this modification: 77 | 78 | ![Screenshot of the message and content while opening a pull requests for the r-svn repository](../img/rsvn_PR_message.png "Describe the changes in the pull request.") 79 | 80 | ![Screenshot of the pull requests opened](../img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") 81 | 82 | Once the PR is submitted, some automatic checks will be triggered (they might need to be approved by some other users as per Github rules): 83 | 84 | ![Screenshot of the checks triggered by opening the pull request](../img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.") 85 | When the checks end you will need to explore the results and asses if the results indicate a problem or not. 86 | 87 | ![Screenshot of the results of the Github checks in the r-svn mirror](../img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.") 88 | 89 | Once you are happy with the changes and the checks report that everything is okay you can retrieve the patch via: 90 | 91 | `https://patch-diff.githubusercontent.com/raw/r-devel/r-svn/pull/.diff` 92 | 93 | Save `.diff` as a plain text file to [submit your patch](#SubmitPatches), remember to check if it meets the [recommendations for good patches](#GoodPatches). 94 | 95 | If you want to use `git` from the terminal to create the pull request (PR) to test the changes, you can use this [summary of the available git commands](https://about.gitlab.com/images/press/git-cheat-sheet.pdf "git cheat sheet"). 96 | 97 | ## Making good patches {#GoodPatches} 98 | 99 | When creating a patch for submission, there are several things that you can do to help ensure that your patch is accepted: 100 | 101 | 1. Make sure to follow [R's coding standards](https://cran.r-project.org/doc/manuals/r-release/R-ints.html#R-coding-standards) (R is a GNU project and there are GNU coding standards). The coding style of the patch you submit should largely match with the codebase it is being applied to. If your patch has one or two minor discrepancies, then those may be fixed by the core developer who will eventually test your patch. However, if there are systematic deviations from the style guides your patch will be put on hold until you fix the formatting issues. There is no comprehensive official R style manual, however some nearly universal standards are summarised in [this article](https://cran.r-project.org/web/packages/rockchalk/vignettes/Rstyle.pdf). 102 | 103 | 2. Be aware of backwards-compatibility considerations. While the core developer who eventually handles your patch will make the final call on whether something is acceptable, thinking about backwards-compatibility early will help prevent having your patch rejected on these grounds. Put yourself in the shoes of someone whose code will be broken by the change(s) introduced by the patch. It is quite likely that any change made will break someone's code, so you need to have a good reason to make a change as you will be forcing someone to update their code. This obviously does not apply to new functions or new arguments. New arguments should be optional and have default values which maintain the existing behaviour. If in doubt, [discuss](#WhereToGetHelp) the issue with experienced developers. 104 | 105 | 3. Make sure you have proper tests to verify that your patch works as expected. Patches may not be accepted without the proper tests. 106 | 107 | 4. Make sure the entire test suite runs without failure because of your changes. It is not sufficient to only run whichever test seems impacted by your changes, because there might be interactions unknown to you between your changes and some other part of the interpreter. 108 | 109 | 5. Proper documentation additions/changes should be included. 110 | 111 | 6. Each bugfix should ideally be addressed by a single patch. In particular, do not fix more than one issue in the same patch (except, if one code change fixes all of them) and do not do cosmetic changes to unrelated code in the same patch as some bugfix. 112 | 113 | ## Submitting your patch for review {#SubmitPatches} 114 | 115 | ### Patch in response to a pre-existing issue or bug report 116 | 117 | In this case, you should attach the patch to the existing issue or bug report on Bugzilla with a brief comment. 118 | 119 | 1. Use the Attachments option to add the `*.diff` file as attachment. 120 | 121 | 2. On the new Create New Attachment web page, add a Brief Description. 122 | 123 | 3. Select Content Type as `patch`. 124 | 125 | 4. Add comments (often prose text) in this page rather than in the original bugzilla page for the PR. 126 | 127 | 5. Press Submit. This will give you a bugzilla submission that sends one e-mail to all of R-core plus the PR author. 128 | 129 | 130 | ### Patch in response to an unreported issue or bug report 131 | 132 | Assuming you already performed a search on Bugzilla for a pre-existing issue or bug and did not find the issue or bug reported, you need to create a new bug report and include your patch with it. Please fill in as much relevant detail as possible to prevent reviewers from having to delay reviewing your patch because of lack of information. Include (mostly as the first sentence), a to-the-point explanation of what the purpose of the patch is. This sentence should not be in the descriptive form, rather an imperative form will be more suitable here. If this is not enough detail for a patch, a new paragraphs(s) can be added to explain in proper depth what has happened. The details should be good enough that a core developer reading it understands the justification for the change. 133 | 134 | ## Getting your patch reviewed {#PatchesReview} 135 | 136 | To begin with, please be patient. There are many more people submitting patches than there are people capable of reviewing your patches. Getting your patch reviewed requires a reviewer to have the spare time and motivation to look at your patch. We cannot force anyone to review patches and no one is employed to look at patches. 137 | 138 | There is a `#patches-for-review` channel on the [R Contributors slack](https://r-contributors.slack.com/) where you can share your patch(es) for review/feedback before submitting to R-Core/Bugzilla. This can help with checking that you have included the important information and excluded redundant information. 139 | 140 | If your patch has not received any notice from reviewers (i.e., no comment made) after one month, comment/message on the `#patches-for-review` channel to remind the members that the patch needs a review. 141 | 142 | When someone does manage to find the time to look at your patch they will most likely make comments about how it can be improved. It is then expected that you update your patch to address these comments, and the review process will thus iterate until a satisfactory solution has emerged. 143 | 144 | ### How to review a patch? 145 | 146 | One of the bottlenecks in the R development process is the lack of code reviews. If you browse Bugzilla, you will see that numerous issues have a fix, but cannot be merged into the main source code repository, because no one has reviewed the proposed solution. Reviewing a patch can be just as informative as providing a patch and it will allow you to give constructive comments on another developer’s work. This guide provides a checklist for submitting a patch review. It is a common misconception that in order to be useful, a patch review has to be perfect. This is not the case at all. It is helpful to just test the patch and/or play around with the code and leave comments in the patch or on Bugzilla. 147 | 148 | If a bug report or an issue has a patch attached that has not been reviewed, you can help by making sure that the patch: 149 | 150 | * follows the style guides; 151 | 152 | * is a good solution to the problem it is trying to solve; 153 | 154 | * includes proper tests; and 155 | 156 | * includes proper documentation changes. 157 | 158 | Also refer to [Making good patches](#GoodPatches) for more ideas. Doing all of this allows the core developer(s) and/ or maintainer(s) to more quickly look for subtle issues that only people with extensive experience working on R's codebase will notice. 159 | 160 | ## Leaving a patch review on Bugzilla 161 | 162 | When you review a patch, you should provide additional details and context of your review process and leave comments. For example: 163 | 164 | 1. If you tested the patch, report the result and the system and version tested on, such as 'Windows 10', 'Ubuntu 16.4', or 'Mac High Sierra'. 165 | 166 | 2. If you request changes, try to suggest how or attach an updated patch. 167 | 168 | 3. Comment on what is 'good' about the patch, not just the 'bad'. Doing so will make it easier for the patch author to find the good in your comments. 169 | 170 | ## Dismissing review from another core developer 171 | 172 | A core developer can dismiss another core developer’s review if they confirmed that the requested changes have been made. When a core developer has assigned the patch to themselves, then it is a sign that they are actively looking after the patch, and their review should not be dismissed. 173 | 174 | ## Acceptance or rejection of your patch 175 | 176 | Once your patch has reached an acceptable state, it will either be applied or rejected. If it is rejected, please do not take it personally. Your work is still appreciated regardless of whether your patch is applied. Balancing what does and does not go into R is tricky and everyone's contributions cannot always be accepted. 177 | 178 | But if your patch is accepted and applied it will then go on to be released with the next patched release and eventually the next major release of R. It may also be backported to older versions of R as a bugfix if the core developer doing the patch acceptance believes it is warranted. 179 | 180 | It may take longer before your patch is accepted and applied or rejected, sometimes even months or years. Nonetheless, it is appreciated that you submitted a patch. 181 | 182 | ## Examples of patch reports on Bugzilla 183 | 184 | 185 | ## Examples of reviewing a patch 186 | 187 | 188 | ## See also 189 | 190 | 1. [Submitting patches](https://www.r-project.org/bugs.html#how-to-submit-patches) 191 | -------------------------------------------------------------------------------- /chapters/message_translations.qmd: -------------------------------------------------------------------------------- 1 | --- 2 | editor_options: 3 | markdown: 4 | wrap: 72 5 | --- 6 | 7 | # Message Translations 8 | 9 | This chapter covers internationalization in R, i.e., the display of 10 | messages in languages other than English. All output in R (such as 11 | messages emitted by `stop()`, `warning()`, or `message()`) is eligible 12 | for translation, as are menu labels in the GUI. Depending on the version 13 | of R that you are using, some of the languages might already be 14 | available while others may need work. R leverages the 15 | [`gettext`](https://www.gnu.org/software/gettext/) program to handle the 16 | conversion from English to arbitrary target languages. 17 | 18 | Having messages available in other languages can be an important bridge 19 | for R learners not confident in English -- rather than learning two 20 | things at once (coding in R and processing diagnostic information in 21 | English), they can focus on coding while getting more natural 22 | errors/warnings in their native tongue. 23 | 24 | The [`gettext` 25 | manual](https://www.gnu.org/software/gettext/manual/index.html) is a 26 | more canonical reference for a deep understanding of how `gettext` 27 | works. This chapter will just give a broad overview, with particular 28 | focus on how things work for R, with the goal of making it as 29 | low-friction as possible for developers and users to contribute 30 | new/updated translations. 31 | 32 | ## How translations work 33 | 34 | Each of the default packages distributed with R (i.e., those found in 35 | `./src/library` such as `base`, `utils`, and `stats` and which have 36 | priority base) contains a `po` directory. A `po` directory is the 37 | central location for ataloguing/translating each package's messages. It 38 | contains a template message file (`.pot`) for the corresponding ackage 39 | along with translated `.po` files (that are created using the template 40 | `.pot` file). 41 | 42 | ### `.pot` files 43 | 44 | A `.pot` file is a template file found inside the `po` directory of an R 45 | package. This template file is a snapshot of the messages available in a 46 | given **domain**. A domain in R typically identifies a source package 47 | and a source language (either R or C/C++). For example, the file 48 | `R-stats.pot` (found in the R sources in `./src/library/stats/po`) is a 49 | catalogue of all messages produced by R code in the `stats` package, 50 | while `stats.pot` is a catalogue of all messages produced by C code in 51 | the `stats` package. 52 | 53 | The 'base' package has two exceptions to the basic pattern described 54 | above. The first is the domain for messages produced by the C code which 55 | is the fundamental backing of R itself (especially, but not exclusively, 56 | the C code under ./src/main[\^The file `./po/POTFILES` is the canonical 57 | source of files searched. Note that while, technically, it is possible 58 | to support translations in Fortran code, R does not currently do so. 59 | Only a handful of messages are produced by Fortran routines in the R 60 | sources.]). The associated `.pot` file is `R.pot` and is found in 61 | `./src/library/base/po`. 62 | R-base.pot`is a normal`.pot`file because base has a normal`R\` 63 | directory. 64 | 65 | The second is the domain for the Windows R GUI, i.e., the text in the 66 | menus and elsewhere in the R GUI program available for running R on 67 | Windows. These messages are stored in the `RGui.pot` domain, also in the 68 | `po` directory for `base`, and are most commonly derived from C code 69 | found in `./src/gnuwin32`. One reason to keep this domain separate is 70 | that it is only relevant to one platform (Windows). In particular, 71 | Windows has historically different character encodings, so that it made 72 | more sense for Windows developers to produce translations specifically 73 | or Windows, since it is non-trivial for non-Windows users to test their 74 | translations for the Windows GUI. 75 | 76 | #### Generating `.pot` files 77 | 78 | For outside contributors, there's no need to update .pot files -- 79 | translators will typically take the R `.pot` files as given and generate 80 | `.po` files. These will be sent along to a language-specific translation 81 | maintainer, who then compiles them to send to the R Core developer 82 | responsible for translations, who finally applies them as a patch. 83 | 84 | To emphasize, this section is almost always not needed for contributing 85 | translations -- it is here for completeness and edification. 86 | 87 | ### `.po` files 88 | 89 | .po files are the most important artifacts for translators. They provide 90 | the (human-readable!) mapping between the messages as they appear in the 91 | source code and how the messages will appear to users in translated 92 | locales. 93 | 94 | #### Singular messages 95 | 96 | Most messages appear as `msgid`/`msgstr` pairs. The former gives the 97 | message as it appears in the code, while the latter shows how it should 98 | appear in translation. For example, here is an error in German (locale: 99 | `de`) informing the user that their input must be of class `POSIXt` 100 | 101 | ``` 102 | msgid "'to' must be a \"POSIXt\" object" 103 | msgstr "'to' muss ein \"POSIXt\" Objekt sein" 104 | ``` 105 | 106 | See this in context in the [`R-de.po` source 107 | file](https://svn.r-project.org/R/trunk/src/library/base/po/R-de.po). 108 | 109 | The same message can also be found in 110 | [`R-it.po`](https://svn.r-project.org/R/trunk/src/library/base/po/R-it.po) 111 | giving the translation to Italian: 112 | 113 | ``` 114 | msgid "'to' must be a \"POSIXt\" object" 115 | msgstr "'to' dev'essere un oggetto \"POSIXt\"" 116 | ``` 117 | 118 | #### Plural messages 119 | 120 | Some messages will have different translations depending on some input 121 | determined at run time (e.g., the `length()` of an input object or the 122 | `nrow()` of a `data.frame`). This presents a challenge for translation, 123 | because different languages have different rules for how to pluralize 124 | different ordinal numbers[\^See the [relevant 125 | section](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) 126 | of the `gettext` manual]. For example, English typically adds `s` to any 127 | quantity of items besides 1 (1 dog, 2 dog`s`, 100 dog`s`, even 0 128 | dog`s`). Chinese typically does not alter the word itself in similar 129 | situations (一只狗, 两只狗, 一百只狗, 零只狗); Arabic has *six* 130 | different ways to pluralize a quantity. 131 | 132 | In `.po` files, this shows up in the form of `msgid_plural` entries, 133 | followed by several ordered `msgstr` entries. Here's an example from 134 | [`R-de.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-de.po#L2015-L2018)[^09-message-translations-1]: 135 | 136 | [^09-message-translations-1]: The GitHub mirror of the [actual svn 137 | repo](https://svn.r-project.org/R/trunk/) is linked in this chapter 138 | as it is a better interface for browsing the source files. 139 | 140 | ``` 141 | msgid "Warning message:\n" 142 | msgid_plural "Warning messages:\n" 143 | msgstr[0] "Warnmeldung:\n" 144 | msgstr[1] "Warnmeldungen:\n" 145 | ``` 146 | 147 | The two entries in English correspond to the singular and plural 148 | messages; the two entries in German correspond similarly, because 149 | pluralization rules in German are similar to those in English. The 150 | situation in Lithuanian 151 | ([`R-lt.po`](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L1999-L2003)) 152 | is more divergent: 153 | 154 | ``` 155 | msgid "Warning message:\n" 156 | msgid_plural "Warning messages:\n" 157 | msgstr[0] "Įspėjantis pranešimas:\n" 158 | msgstr[1] "Įspėjantys pranešimai:\n" 159 | msgstr[2] "Įspėjančių pranešimų:\n" 160 | ``` 161 | 162 | This corresponds to the 3 different ways to pluralize words in Polish. 163 | 164 | What do `0`, `1`, and `2` correspond to, exactly? Ideally, this will be 165 | clear to native speakers of the language, but for clarity, it is the 166 | solution to a small arithmetic problem that can be found in the 167 | language's metadata entry. Look for the `Plural-Forms` entry in the 168 | metadata at the top of the `.po` file; [here it is for 169 | Lithuanian](https://github.com/r-devel/r-svn/blob/c715d61cb74b3fee2d035faed9b258e86e420b75/src/library/base/po/R-lt.po#L18-L19): 170 | 171 | ``` 172 | "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n" 173 | "%100<10 || n%100>=20) ? 1 : 2);\n" 174 | ``` 175 | 176 | `nplurals` tells us how many entries correspond to each `msgid_plural` 177 | for this language. `plural` tells us, for the quantity `n`, which entry 178 | to use. The arithmetic is C code; most important if you really want to 179 | parse this and are only familiar with R code is C's [ternary 180 | operator](https://en.wikipedia.org/wiki/%3F:): 181 | `test ? valueIfTrue : valueIfFalse` is a handy way to write R's 182 | `if (test) valueIfTrue else valueIfFalse`. 183 | 184 | Parsing, we get the following associations: 185 | 186 | - the `0` entry corresponds to when a number equals 1 modulo 10 (i.e., 187 | 1, 11, 21, 31, ...) *except* numbers equaling 11 modulo 100 (i.e., 188 | 11, 111, 211, 311, ...). Combining, that's 1, 21, 31, ..., 91, 101, 189 | 121, 131, ..., 191, ... 190 | - the `1` entry corresponds to numbers at least 2 modulo 10 (2, 3, 191 | ..., 8, 9, 12, 13, 14, ...) and *either* below 10 modulo 100 (0, 1, 192 | ..., 9, 100, 101, ..., 109, ...) *or* exceeding 20 modulo 100 (21, 193 | 22, ..., 99). Combining, that's 2, 3, ..., 9, 22, 23, ..., 29, 32, 194 | 33, ... 39, ..., 102, 103, ..., 109, 122, 123, ... 195 | - The `2` entry corresponds to all other numbers, i.e. 0, 10, 11, 12, 196 | ..., 19, 20, 30, ..., 90, 100, 110, 111, 112, ... 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | ### `.mo` files 205 | 206 | `.po` files are plain text, but while helpful for human readers, this is 207 | inefficient for consumption by computers. The .mo format is a "compiled" 208 | version of the .po file optimized for retrieving messages when R is 209 | running. 210 | 211 | In R-devel, the conversion from .po to .mo is done by R Core -- you 212 | don't need to compile these files yourself. They are stored in the R 213 | sources at `./src/library/translations/inst` in various 214 | language-specific subdirectories. 215 | 216 | ## How to contribute new translations 217 | 218 | 219 | 220 | Translating R into different languages helps make it more user-friendly 221 | for non-English speakers and helps to grow the R community. See the blog 222 | post on how [R can use your help: Translating R 223 | messages](https://blog.r-project.org/2022/07/25/r-can-use-your-help-translating-r-messages). 224 | 225 | To get started contributing to translations, please follow the steps 226 | below: 227 | 228 | **Step 1: Register an Account at Weblate** 229 | 230 | Weblate is an open-source platform for collaborative translation of 231 | software projects. Register an account on R's Weblate server, 232 | , to start contributing. 233 | 234 | > *Note: To get started follow the detailed workflow and convention for 235 | > translation which is given here: 236 | > * 237 | 238 | **Step 2: Choose a Component and Language** 239 | 240 | Select a component of R with less than 100% translation. Each component 241 | corresponds to the messages in either the R code or the C code of one of 242 | the packages in base R, e.g. base (R files), or tools (C files). There 243 | is one special case: base (R GUI), which corresponds to the messages in 244 | the Windows Graphical User Interface. 245 | 246 | After selecting a component, you can select your preferred language. 247 | 248 | ![](../img/translate_component.png) 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | **Step 3: Translate the Message** 263 | 264 | Now, you can click on Translate button on your right. 265 | 266 | > Note: More information for String status visit: 267 | > 268 | 269 | ![](../img/translate_button.png) 270 | 271 | Then, start translating the message by typing the translation in the 272 | text box. 273 | 274 | ![](../img/translate_string_and_save.png) 275 | 276 | - If you are **confident** that the **translation is correct**, make 277 | sure the "Needs editing" box is **unchecked**. 278 | 279 | - If you are **unsure** about how to translate, write the translation 280 | as a **Suggest** button instead. 281 | 282 | - Finally, Click **"Save and Continue"** to save the translation and 283 | continue. 284 | 285 | ------------------------------------------------------------------------ 286 | 287 | > **Note:** Use Glossary feature within Weblate making translation easy 288 | > and consistent: 289 | > 290 | 291 | > **Note:** Make sure to use Automatic Suggestions as a starting point. 292 | 293 | 1. Click on Automatic Suggestions (machine translation) 294 | 295 | 2. Accept it if you think the automatic suggestion looks good 296 | 297 | ![](../img/auto-suggestion.png) 298 | 299 | ------------------------------------------------------------------------ 300 | 301 | **Some Tips to follow:** 302 | 303 | - **Be consistent:** Use the same words and phrases throughout the 304 | translation to make it consistent and avoid confusion. 305 | 306 | - **Check for technical issues:** After finishing the translation, 307 | check if you have any alerts or warning in the Weblate string 308 | status, e.g. double instead of single space. 309 | 310 | - **Follow language specific guidelines:** Check how other languages 311 | have translated the string. Even if you are not fluent in another 312 | language it can give you an idea of how other translators have 313 | handled it, especially which parts are left verbatim. A detailed 314 | guide is given here : 315 | [Conventions-for-translations#languages-and-contributions](https://contributor.r-project.org/translations/Conventions_for_Languages/#languages-and-contributions){.uri} 316 | 317 | Related links: 318 | 319 | 320 | 321 | ## Bulk Translations 322 | 323 | Instead of translating one string at a time, it is possible to bulk translate a whole component of R at once: 324 | 325 | 1. Navigate to the translations for a particular component in a particular language, e.g. https://translate.rx.studio/projects/r-project/base-c/ar/ 326 | 327 | 2. Select **'Tools > Automatic translation'** 328 | 329 | ![Tools drop-down menu with "Automatic Translations" selected](../img/translate_automatic_translation.png) 330 | 331 | 332 | 3. In the dialog, 333 | - under **'Automatic translation mode'**, select **'Add as "needing edit"'**[^09-message-translations-2]: 334 | 335 | 336 | [^09-message-translations-2]: By selecting **'Add as "needing edit"'**, the autotranslated strings would be treated as "fuzzy" translations, i.e. they would be added to the component source files when a patch is made, but they would NOT be used. 337 | 338 | - under **'Search filter'**, select **'Untranslated strings'** 339 | - under **'Source of automated translations'**, select **'Machine translation'** 340 | - under **'Machine translation engines'**, select **'Microsoft Translator'**[^09-message-translations-3]: 341 | 342 | 343 | [^09-message-translations-3]: Microsoft Translator is preferred for bulk translation as our free tier covers 2 million characters/month, where DeepL only allows 500k chars/month. If Microsoft Translator translations are much worse than DeepL, it may be useful to use it to translate one string at a time. 344 | 345 | ![Automatic Translations dialog box](../img/translate_dialog.png) 346 | 347 | 4. Review the translations, edit as necessary and uncheck **"needing edit"**. 348 | 349 | ## Current status of translations in R 350 | 351 | 352 | 353 | ## Helpful references 354 | 355 | - [Statistical terms glossary](https://www.isi-web.org/glossary) 356 | - The [R Translations site](https://contributor.r-project.org/translations/) contains more details on translating R messages and getting involved in existing projects. 357 | -------------------------------------------------------------------------------- /chapters/news_and_announcements.qmd: -------------------------------------------------------------------------------- 1 | # News and Announcements {#News} 2 | 3 | Here are some resources that can be useful to keep up with the developments in R: 4 | 5 | ## Blogs 6 | 7 | The [R project](https://www.r-project.org/) maintains [The R Blog](https://blog.r-project.org/) with posts mainly written by the R Core Team. News of changes in the development version of R found on the [Daily News about R-devel](https://developer.r-project.org/blosxom.cgi/R-devel) blog which is updated daily. 8 | 9 | ## Conferences 10 | 11 | Updates about conferences actively supported or endorsed by The R Foundation can be found [here](https://www.r-project.org/conferences/). These conferences are organised by members from the R community. 12 | 13 | ## Journal 14 | 15 | [The R Journal](https://journal.r-project.org/) is an open access and refereed journal featuring short to medium length articles that should be of interest to users or developers of R. It also has a news section where information on, changes in R (new features of the latest release), changes on CRAN (new add-on packages, manuals, binary contributions, mirrors, etc.), upcoming conferences, and conference reports is provided. 16 | 17 | ## Mailing lists 18 | 19 | * [R-announce](https://stat.ethz.ch/mailman/listinfo/r-announce): A moderated mailing list used for announcements by the R Core Development Team. Major announcements about the development of R and the availability of new code are made here. 20 | * [R-packages](https://stat.ethz.ch/mailman/listinfo/r-packages): A moderated mailing list for announcements about contributed R packages (typically on [CRAN](https://cran.r-project.org/)) and similar R project extensions. 21 | 22 | ## Twitter 23 | 24 | Follow [\@R_dev_news](https://twitter.com/R_dev_news) on Twitter for news of [changes in the development version of R](https://developer.r-project.org/RSSfeeds.html) and new posts on [The R Blog](https://blog.r-project.org/) announcements. 25 | -------------------------------------------------------------------------------- /chapters/r_core_developers.qmd: -------------------------------------------------------------------------------- 1 | # R Core Developers {#CoreDev} 2 | 3 | This page lists the current and former members of the R Core Team who have write access to the R source. 4 | 5 | Current members of the R Core Team: 6 | 7 | * [John Chambers](https://datascience.stanford.edu/people/john-chambers) 8 | * [Peter Dalgaard](www.cbs.dk/en/staff/pdmes) 9 | * [Robert Gentleman](https://en.wikipedia.org/wiki/Robert_Gentleman_(statistician)) 10 | * [Kurt Hornik](https://statmath.wu.ac.at/~hornik/software.html) 11 | * [Ross Ihaka](https://en.wikipedia.org/wiki/Ross_Ihaka) 12 | * [Tomas Kalibera](https://github.com/kalibera) 13 | * [Michael Lawrence](https://github.com/lawremi) 14 | * [Uwe Ligges](https://www.statistik.tu-dortmund.de/~ligges/) 15 | * [Thomas Lumley](https://github.com/tslumley) 16 | * [Martin Maechler](https://people.math.ethz.ch/~maechler/) 17 | * [Sebastian Meyer](https://www.imbe.med.fau.de/lehrstuhl/sebastian-meyer/) 18 | * [Paul Murrell](https://www.stat.auckland.ac.nz/~paul/) 19 | * [Martyn Plummer](https://warwick.ac.uk/fac/sci/statistics/staff/academic-research/plummer/) 20 | * [Brian Ripley](https://www.stats.ox.ac.uk/~ripley/) 21 | * [Deepayan Sarkar](https://www.isid.ac.in/~deepayan/) 22 | * [Duncan Temple Lang](https://www.stat.ucdavis.edu/~duncan/) 23 | * [Luke Tierney](https://stat.uiowa.edu/people/luke-tierney) 24 | * [Simon Urbanek](https://urbanek.info/) 25 | 26 | Former members of the R Core team: 27 | 28 | * Friedrich Leisch (up to April 2024) 29 | * Douglas Bates (up to March 2024) 30 | * Martin Morgan (up to June 2021) 31 | * Duncan Murdoch (up to September 2017) 32 | * Seth Falcon (up to August 2015) 33 | * Stefano lacus (up to July 2014) 34 | * Guido Masarotto (up to June 2003) 35 | * Heiner Schwarte (up to October 1999) 36 | 37 | The [Contributors page on the R Project website](https://www.r-project.org/contributors.html) also lists specific contributors outside the R Core Team who have provided invaluable help by donating code, bug fixes, and documentation. 38 | -------------------------------------------------------------------------------- /chapters/reporting_bugs.qmd: -------------------------------------------------------------------------------- 1 | # Reporting Bugs {#ReportingBugs} 2 | 3 | ## What is a bug in R? 4 | 5 | You may find a bug in R if: 6 | 7 | 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: 8 | 9 | ```r 10 | ## *** caught segfault *** 11 | ## address (nil), cause 'memory not mapped' 12 | ``` 13 | 14 | 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. 15 | 16 | **Note**: 17 | When you are in doubt that there is a bug: (which should be the case most of the time!) 18 | 19 | 1. 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 `--vanilla` option. 20 | 21 | 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 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. 22 | 23 | 3. Install R-devel, which is the most recent version of R from [svn](https://svn.r-project.org/R/trunk/) / [git](https://github.com/r-devel/r-svn) or [daily Windows build](https://cran.r-project.org/bin/windows/base/rdevel.html), and see if your bug still exists in R-devel (it may have been fixed very recently). 24 | 25 | 4. [Search on the R-devel mailing list for messages with keywords related to your possible bug](https://www.mail-archive.com/r-devel@r-project.org/index.html). 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. 26 | 27 | ## What condition might not be a bug? 28 | 29 | 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. 30 | 31 | 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. 32 | 33 | 3. 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. 34 | 35 | 4. 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. 36 | 37 | ## Checking if a bug is already reported {#already-reported-bugs} 38 | 39 | 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: 40 | 41 | 1. Save time for you and the developers. 42 | 43 | 2. Help you see if the bug is already fixed for the next release. 44 | 45 | 3. Lead you to learn what needs to be done to fix it. 46 | 47 | 4. Determine if any additional information is needed. 48 | 49 | The sections that follow discuss where to check whether a bug is already reported. 50 | 51 | ## What are some places where you may find a bug? 52 | 53 | You may find a bug in: 54 | 55 | 1. In the [R-Core supported packages, their documentations, and/ or in the R language implementation](#RCorePkgBug). 56 | 57 | 2. In [packages and/or their documentations which are not supported by the R-Core](#nonRCorePkgBug). 58 | 59 | ## How to report a bug? {#ReportBug} 60 | 61 | Once you confirm a bug exists, you need to submit a bug report so that it gets fixed. 62 | 63 | ### Bug in the R-Core supported packages, their documentations, and/ or in the R language {#RCorePkgBug} 64 | 65 | 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. 66 | 67 | 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-devel, [see posting guide](https://www.r-project.org/posting-guide.html#which_list), or to [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 the R svn server](https://github.com/r-devel/r-svn/issues). 68 | 69 | 3. In order to report bugs, as well as fixes, using [Bugzilla](#Bugzilla), please ensure that you have a [Bugzilla account](#bugzilla-account) 70 | 71 | 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), using 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)). 72 | 73 | ### Bug in the non R-Core supported packages and/or their documentations {#nonRCorePkgBug} 74 | 75 | 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 `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. 76 | 77 | ### Bug in a documentation website managed by the R Core Team {#docWebsRCoreBug} 78 | 79 | The R Core Team maintain a selection of websites that each have their own ways for reporting issues outside of Bugzilla. Have a read through the [posting guide for R project mailing lists](https://www.r-project.org/posting-guide.html) and then follow the instructions below to give feedback to the maintainers. 80 | 81 | - [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html) contains answers to some of the most frequently asked questions about R. Feedback on the R FAQ should be sent to the [R-devel mailing list](https://stat.ethz.ch/mailman/listinfo/r-devel) via [R-devel@R-project.org](mailto:R-devel@R-project.org). 82 | - [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) contains answers specific to the Windows port of R. Feedback on the Windows FAQ should be sent to the [R-SIG-windows mailing list](https://stat.ethz.ch/mailman/listinfo/r-sig-windows) (the Special Interest Group for Windows), via [R-windows@R-project.org](mailto:R-windows@R-project.org). 83 | - [R for macOS FAQ](https://cran.r-project.org/bin/macosx/RMacOSX-FAQ.html) contains a user guide to the R.APP version of R and information on using R on macOS, supplementing the main R manuals. Feedback on the macOS FAQ should be sent to the [R-SIG-Mac mailing list](https://stat.ethz.ch/mailman/listinfo/r-sig-mac) (the Special Interest Group for Mac ports of R), via [r-sig-mac@r-project.org](mailto:r-sig-mac@r-project.org). 84 | - Feedback on the [R Project website](https://www.r-project.org/) should be sent to [webmaster@r-project.org](mailto:webmaster@r-project.org). 85 | - Feedback on the website for [The Comprehensive R Archive Network](https://cran.r-project.org/) (CRAN) should be sent to [cran-sysadmin@r-project.org](mailto:cran-sysadmin@r-project.org). 86 | 87 | ## Good practices in reporting bugs / Expectations of a good bug report {#good-practices-bugs} 88 | 89 | 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. 90 | 91 | 1. 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 [community wiki post](https://stackoverflow.com/questions/5963269/how-to-make-a-great-r-reproducible-example) on how to make a minimal reproducible example. 92 | 93 | 2. Mention the software architecture on which the bug occurred. 94 | 95 | 3. Use inbuilt data sets as far as possible. 96 | 97 | 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 discusses practices to write a good bug report. 98 | 99 | 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. 100 | 101 | ## Disagreement with a resolution on the bug tracker 102 | 103 | 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. 104 | 105 | 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. 106 | 107 | 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). 108 | 109 | ## Examples of Bug reports submitted on Bugzilla or R-devel mailing list 110 | 111 | If you like to see how bugs are reported on Bugzilla, here are some examples: 112 | 113 | 1. [Bug 17767 - Warning about incomplete argument within nlme](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17767): A bug report with a reproducible example, a patch, and a review. 114 | 115 | 2. [Possible bug when finding shared libraries during staged installation](https://stat.ethz.ch/pipermail/r-devel/2019-May/077855.html): 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 [here](https://stat.ethz.ch/mailman/listinfo/r-devel)). 116 | 117 | 3. [Bug: time complexity of substring is quadratic as string size and number of substrings increases](https://stat.ethz.ch/pipermail/r-devel/2019-February/077393.html): A substring reported by Toby Dylan Hocking and fixed by Tomas Kalibera, Feb 2019 via the R-devel mailing list. 118 | 119 | 4. [patch for gregexpr(perl=TRUE)](https://stat.ethz.ch/pipermail/r-devel/2019-February/077315.html): A gregexpr bug report and patch submitted by Toby Dylan Hocking and merged by Tomas Kalibera, Feb 2019 via the R-devel mailing list. 120 | 121 | ## See also 122 | 123 | 1. [Reporting a bug](https://www.r-project.org/bugs.html) 124 | 125 | 2. [R FAQ on bugs](https://mac.r-project.org/man/R-FAQ.html#R-Bugs) 126 | 127 | 3. [Bugzilla guidelines of reporting a bug](https://bugs.r-project.org/bugzilla/page.cgi?id=bug-writing.html) 128 | -------------------------------------------------------------------------------- /chapters/reviewing_bugs.qmd: -------------------------------------------------------------------------------- 1 | # Reviewing Bugs {#ReviewBugs} 2 | 3 | ## How you can help to review bug reports? 4 | 5 | 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. 6 | 7 | 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. 8 | 9 | ### Preparing to review bug reports 10 | 11 | If you want to review bug reports on Bugzilla, you are required to have a [Bugzilla account](#bugzilla-account). More details on how you can review a bug report are available on this post on the R Blog: [R Can Use Your Help: Reviewing Bug Reports](https://blog.r-project.org/2019/10/09/r-can-use-your-help-reviewing-bug-reports/index.html) 12 | 13 | ## Classifying bug reports 14 | 15 | A good bug report is the one which: 16 | 17 | 1. Explains clearly how to reproduce the bug. 18 | 19 | 2. Includes the version of R, the machine architecture, and the operating system platform on which the bug occurred. 20 | 21 | 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: 22 | 23 | 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). 24 | 25 | 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. 26 | 27 | 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. 28 | 29 | 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. 30 | 31 | ## How to find a bug report or an issue to review? 32 | 33 | 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. 34 | 35 | 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). 36 | 37 | ## Example of a bug review submitted on Bugzilla 38 | 39 | If you would like to see how bugs are reviewed on Bugzilla, the [Bug 16542 - `nlme:::summary.lmList` with unequal outputs per group](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. 40 | 41 | ::: {.callout-note} 42 | There is a `#bug-reporting` channel on the [R Contributors slack](https://r-contributors.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. 43 | ::: 44 | 45 | ## See also 46 | 47 | 1. [Reviewing bug reports: Blog](https://blog.r-project.org/2019/10/09/r-can-use-your-help-reviewing-bug-reports/index.html) 48 | -------------------------------------------------------------------------------- /chapters/submitting_feature_requests.qmd: -------------------------------------------------------------------------------- 1 | # Submitting Feature Requests {#FeatureRequests} 2 | 3 | ## What is a feature request? 4 | 5 | A feature request is a suggestion or proposal to add new functionality or improve an existing feature. 6 | 7 | We recommend sharing your feature request idea on the [R-devel](https://stat.ethz.ch/mailman/listinfo/r-devel) mailing list and gaining support from R-Core members and other users to increase its likelihood of acceptance. 8 | 9 | ## How to submit a feature request? 10 | 11 | You can submit a feature request by [filing a bug](https://bugs.r-project.org/enter_bug.cgi) on Bugzilla. Under Component, select "Wishlist", the designated label for feature requests. 12 | 13 | ![The "Wishlist" component in Bugzilla's bug submission screen.](../img/feature-requests.png) 14 | 15 | Similar to bugs, you should ensure that the feature request is [not already reported](#already-reported-bugs) and [follow best practices](#good-practices-bugs) whenever possible. 16 | 17 | ## Examples of feature requests submitted on Bugzilla 18 | 19 | If you like to see how feature requests are reported on Bugzilla, here are some examples: 20 | 21 | 1. [Bug 18690 - Increase CONSOLE_BUFFER_SIZE and / or warn if input is truncated](https://bugs.r-project.org/show_bug.cgi?id=18690): A feature request to ease the readability of long lines. 22 | 2. [Bug 17912 - ordering elements in sessionInfo() by alphabetical order](https://bugs.r-project.org/show_bug.cgi?id=17912): A feature request that was not accepted due to the prioritization of load time in session information. 23 | -------------------------------------------------------------------------------- /chapters/testing_pre_release_r_versions.qmd: -------------------------------------------------------------------------------- 1 | # Testing Pre-release R Versions {#TestRVer} 2 | 3 | This chapter is inspired from the blog on [testing R before release](https://blog.r-project.org/2021/04/28/r-can-use-your-help-testing-r-before-release/index.html) and discusses how you can help with testing of pre-release versions of R. 4 | 5 | ## Where to test? 6 | 7 | Whenever possible use a fresh package library for testing, even better would be to use [virtual machines](#VM) for the testing. This would ensure that you do not damage your existing R installation. 8 | 9 | ### Virtual machine {#VM} 10 | 11 | A free Windows 10 virtual machine is provided by Microsoft (with a 90-day limit) for building, testing, and checking R packages and R itself. Package maintainers who work on Linux and MacOS can use it to test their packages on Windows. Read the [instructions](https://svn.r-project.org/R-dev-web/trunk/WindowsBuilds/winutf8/ucrt3/vm.html) on how to automatically set up the machine to check R packages. Tomas Kalibera describes the details of using virtual machine in the blog [Virtual Windows machine for checking R packages](https://blog.r-project.org/2021/03/18/virtual-windows-machine-for-checking-r-packages/index.html). 12 | 13 | ## What can you test? 14 | 15 | You can test: 16 | 17 | * Your own programs. 18 | 19 | * Your own workflows. 20 | 21 | * Your special ways of installing or setting up R. 22 | 23 | * Things that interact with external libraries. 24 | 25 | * Interactive R packages. 26 | 27 | Details of performing testing on various operating systems: 28 | 29 | * [Windows](https://blog.r-project.org/2021/04/28/r-can-use-your-help-testing-r-before-release/index.html#on-windows) 30 | 31 | * [macOS](https://blog.r-project.org/2021/04/28/r-can-use-your-help-testing-r-before-release/index.html#on-macos) 32 | 33 | * [Linux](https://blog.r-project.org/2021/04/28/r-can-use-your-help-testing-r-before-release/index.html#on-linux) 34 | 35 | * [Solaris](https://blog.r-project.org/2021/04/28/r-can-use-your-help-testing-r-before-release/index.html#on-solaris) 36 | 37 | ## Writing tests for R 38 | 39 | Writing tests for R is much like writing tests for your own code. Tests need to be thorough, fast, isolated, consistently repeatable, and as simple as possible. 40 | 41 | When you are adding tests to an existing test file, it is also recommended that you study the other tests in that file; it will teach you which precautions you have to take to make your tests robust and portable. We try to have tests both for normal behaviour and for error conditions. Tests live in the `tests` directory. 42 | 43 | ## Benchmarks 44 | 45 | Benchmarking is useful to test that a change does not degrade performance. 46 | -------------------------------------------------------------------------------- /chapters/where_to_get_help.qmd: -------------------------------------------------------------------------------- 1 | # Where to Get Help {#WhereToGetHelp} 2 | 3 | If you are working on R it is possible that you will come across an issue where you would need some assistance to solve it. If you require help, there are options available to seek assistance or get some feedback which are discussed in this chapter. If the question involves process or tool usage then please check the rest of this guide first as it should answer your question. Please make sure to search the documentation and resources to see if your question has already been addressed. If not, then ask for assistance in the appropriate forum. Many developers are volunteers and please be polite, patient, and thoughtful when requesting for feedback or help. 4 | 5 | ## Slack 6 | 7 | You can discuss issues related to the development of R and learn about the process of contributing to R on the [R Contributors slack](https://r-contributors.slack.com/). There are a number of experienced developers on this slack who can answer questions and/or provide feedback. The following channels are available on the R-devel slack for help and feedback with specific areas: 8 | 9 | * #bugreports-for-review: Share bug reports for review/feedback before submitting to Bugzilla. 10 | 11 | * #core-dev-help: Getting help on anything related to R Core contribution. 12 | 13 | * #core-documentation: Discuss patches/improvements to R's documentation. 14 | 15 | * #core-translation: Discuss translating R messages, warnings, and errors into non-English languages. 16 | 17 | * #patches-for-review: Share patches for peer review before submitting to R Core. 18 | 19 | Note: You may not be able to access the history of these channels, so it cannot be used as a knowledge base of sorts. 20 | 21 | ## Mailing lists 22 | 23 | There are quite a few [mailing lists](https://www.r-project.org/mail.html) for getting help with R: 24 | 25 | * [R-devel](https://stat.ethz.ch/mailman/listinfo/r-devel): 26 | * Questions and discussion about development _of_ R vs. _with_ R. 27 | * Getting help with technical programming issues, e.g. interfacing R with C/C++. 28 | * Proposals of new functionality/feature requests for R. 29 | * Pre-testing of new versions of R. 30 | * Enhancements and patches to the R source code and the R documentation. 31 | * Posting examples and benchmarks. 32 | 33 | * [R-help](https://stat.ethz.ch/mailman/listinfo/r-help): 34 | * Discussions about problems and solutions using R. 35 | 36 | * [R-package-devel](https://stat.ethz.ch/mailman/listinfo/r-package-devel): 37 | * Getting help about package development in R. 38 | * Learning about the package development process. 39 | * Discussing problems developing a package (or problem in passing the R CMD check). 40 | 41 | Please avoid cross-posting to both the R-package-devel and the R-devel mailing lists. 42 | 43 | ## File a bug 44 | 45 | If you strongly suspect you have come across a bug (be it in the build process, or in other areas), then [report it on Bugzilla](#ReportBug). 46 | -------------------------------------------------------------------------------- /css/theme-dark.scss: -------------------------------------------------------------------------------- 1 | /*-- scss:defaults --*/ 2 | // Base document colors 3 | $body-bg: #181818; 4 | $body-color: white; 5 | $link-color: #75AADB; 6 | 7 | // Code blocks 8 | $code-block-bg-alpha: -.8; -------------------------------------------------------------------------------- /html/header.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /img/02-trgz.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/02-trgz.png -------------------------------------------------------------------------------- /img/Rlogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/Rlogo.png -------------------------------------------------------------------------------- /img/Rlogo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /img/auto-suggestion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/auto-suggestion.png -------------------------------------------------------------------------------- /img/bot-usage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bot-usage.png -------------------------------------------------------------------------------- /img/bugzilla-adv-search-detailed-bug-info.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bugzilla-adv-search-detailed-bug-info.png -------------------------------------------------------------------------------- /img/bugzilla-adv-search-home.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bugzilla-adv-search-home.png -------------------------------------------------------------------------------- /img/bugzilla-adv-search-search-by-change-history.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bugzilla-adv-search-search-by-change-history.png -------------------------------------------------------------------------------- /img/bugzilla-adv-search-search-by-people.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bugzilla-adv-search-search-by-people.png -------------------------------------------------------------------------------- /img/bugzilla.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/bugzilla.png -------------------------------------------------------------------------------- /img/ccby.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/ccby.png -------------------------------------------------------------------------------- /img/commonquery.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/commonquery.png -------------------------------------------------------------------------------- /img/cover_page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/cover_page.png -------------------------------------------------------------------------------- /img/cover_page_scriberia.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/cover_page_scriberia.pdf -------------------------------------------------------------------------------- /img/cover_page_scriberia.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/cover_page_scriberia.png -------------------------------------------------------------------------------- /img/cover_page_scriberia.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/cover_page_scriberia.pptx -------------------------------------------------------------------------------- /img/edit_icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/edit_icon.png -------------------------------------------------------------------------------- /img/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/favicon.png -------------------------------------------------------------------------------- /img/feature-requests.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/feature-requests.png -------------------------------------------------------------------------------- /img/information.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 6 | 7 | 9 | 11 | 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 | -------------------------------------------------------------------------------- /img/lightbulb.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 8 | 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 | -------------------------------------------------------------------------------- /img/quicksearch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/quicksearch.png -------------------------------------------------------------------------------- /img/r-dev-guide-without-text.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/r-dev-guide-without-text.jpg -------------------------------------------------------------------------------- /img/r-development-guide.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/r-development-guide.jpg -------------------------------------------------------------------------------- /img/rsvn_PR_automatic_checks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_PR_automatic_checks.png -------------------------------------------------------------------------------- /img/rsvn_PR_created.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_PR_created.png -------------------------------------------------------------------------------- /img/rsvn_PR_message.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_PR_message.png -------------------------------------------------------------------------------- /img/rsvn_checks_results.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_checks_results.png -------------------------------------------------------------------------------- /img/rsvn_commit_message.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_commit_message.png -------------------------------------------------------------------------------- /img/rsvn_commit_pre_PR.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_commit_pre_PR.png -------------------------------------------------------------------------------- /img/rsvn_edit_file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_edit_file.png -------------------------------------------------------------------------------- /img/rsvn_file_to_edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/rsvn_file_to_edit.png -------------------------------------------------------------------------------- /img/squarebuttons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/squarebuttons.png -------------------------------------------------------------------------------- /img/translate_automatic_translation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/translate_automatic_translation.png -------------------------------------------------------------------------------- /img/translate_button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/translate_button.png -------------------------------------------------------------------------------- /img/translate_component.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/translate_component.png -------------------------------------------------------------------------------- /img/translate_dialog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/translate_dialog.png -------------------------------------------------------------------------------- /img/translate_string_and_save.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/translate_string_and_save.png -------------------------------------------------------------------------------- /img/unfinished_strings_translate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/rdevguide/cf66e37cf9d4eb22098f727261190748ff61db26/img/unfinished_strings_translate.png -------------------------------------------------------------------------------- /index.qmd: -------------------------------------------------------------------------------- 1 | # {-} 2 | 3 | ![R Development Guide. This illustration is created by Scriberia with The Turing Way community, used under a CC-BY 4.0 licence. DOI: https://zenodo.org/records/13882307](img/r-dev-guide-without-text.jpg){height=400px width=550px} 4 | 5 | # Acknowledgement {-} 6 | 7 | This guide draws on documentation and articles written by the R Core Team. The first version of the guide was heavily influenced by the [Python Developer's Guide](https://devguide.python.org/). 8 | 9 | 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 [Google Season of Docs 2022](https://github.com/rstats-gsod/gsod2022/wiki/GSOD-2022-Proposal) project with Saranjeet Kaur Bhogal and Lluís Revilla Sancho working as technical writers managed by Nicolas Bennett and overseen by a [Steering Committee](https://github.com/rstats-gsod/gsod2022/wiki/GSOD-2022-Proposal#steering-committee) including representatives from R Core and the wider R community. 10 | 11 | This guide has benefited and continues to benefit from varied contributions by several [contributors](https://github.com/r-devel/rdevguide#contributors-). 12 | 13 | 14 | [![License: CC BY 4.0](img/ccby.png)](https://creativecommons.org/licenses/by/4.0/){width=180px} 15 | 16 | This project is licensed under a [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). Some pages may contain materials that are subject to copyright, in which case you will see the copyright notice. 17 | -------------------------------------------------------------------------------- /rdevguide.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Website 19 | -------------------------------------------------------------------------------- /tex/frontpage.tex: -------------------------------------------------------------------------------- 1 | \includepdf[pages={1}, scale=1]{img/cover_page_scriberia.pdf} 2 | \newpage 3 | 4 | \let\maketitle\oldmaketitle 5 | \maketitle 6 | -------------------------------------------------------------------------------- /tex/preamble.tex: -------------------------------------------------------------------------------- 1 | \usepackage{booktabs} 2 | \usepackage{pdfpages} 3 | \usepackage{amsthm} 4 | \makeatletter 5 | \def\thm@space@setup{% 6 | \thm@preskip=8pt plus 2pt minus 4pt 7 | \thm@postskip=\thm@preskip 8 | } 9 | \makeatother 10 | \let\oldmaketitle\maketitle 11 | \AtBeginDocument{\let\maketitle\relax} 12 | --------------------------------------------------------------------------------