README.md

Exercism R Track

Exercism problems in R

Contributing Guide

• Asking for help
• How to contribute
  • Reporting or fixing bugs
  • Reviewing issues and pull requests
  • Porting exercises
  • Updating an exercise test suite
• Repository structure and conventions
  • Directory structure
  • Exercise structure
• Writing an issue
• Writing a pull request
• Development Dependencies
• Example Solution
• Test Suite
• Running Tests
• R Style Guide

Asking for help

If stuck or in doubt just ask! We try our best to be friendly and helpful, so don't be shy!

• gitter support: general questions about exercism, setup, track content etc.
• gitter dev: technical questions.

How to contribute

As a first step we recommend you read the contributing guide.

Reporting or fixing bugs

Typical examples for a bug: A typo, a missing test case, an unclear or ambiguous problem description.

• If you are unsure whether you have really found a bug just ask.
• To report a bug you can write an issue.
• If you have a fix you can write a pull request.

Reviewing issues and pull requests

If you have a dedicated opinion you are welcome to write a comment for an issue or a pull request. Please be detailed and include motivations or relevant links to support your opinion.

Porting exercises

Here is the list of missing exercises. See here for more information about porting an exercise. Of course you can also add a totally new exercise, but it might be a good idea to first discuss it in one of our forums.

Updating an exercise test suite

Updating the test suite of an existing exercise is a special case because it usually affects all languages. Read more about it here. Note that the test suite must run within a couple of seconds.

Repository structure and conventions

A general description of all the files and directories can be found here.

Directory structure

├── .gitignore
├── .travis.yml
├── .github
│ └── stale.yml
├── config.json
├── README.md
└── LICENSE
├── img
│ └── icon.png
├── bin
│ ├── fetch‐configlet
│ ├── run_lints.R
│ └── run_tests.R
├── docs
│ ├── ABOUT.md
│ ├── INSTALLATION.md
│ ├── LEARNING.md
│ ├── RESOURCES.md
│ └── TESTS.md
└── exercises
  ├── TRACK_HINTS.md
  ├── <exercise-name>
  │ ├── <exercise-name>.R
  │ ├── example.R
  │ └── test_<exercise-name>.R
  ├── <exercise-name>
  │ ├── <exercise-name>.R
  │ ├── example.R
  │ └── test_<exercise-name>.R
  └── ...

• config.json: Note that every exercise has to be registered here, with a unique name and a difficulty. The sequence order in this file determines the default order in which the exercises are fetched.

Exercise structure

Each exercise has the following structure:

• <exercise-name>.R usually contains an empty function declaration, as a starting point for the required solution.
• example.R is the source code of the sample solution.
• test_<exercise-name>.R is the test suite.
• HINTS.md is an optional file containing instructions and/or hints. It is used together with the respective description.md for the exercise from x-common to build the README.md file.

Writing an issue

To report a bug you should create an issue here.

Writing a pull request

To fix a bug you should create a pull request from a fork here. See also here for more information.

Development dependencies

You'll need to have a recent version of R installed on your system, as well as the testthat package (run install.packages('testthat') from the R console to install) in order to run tests.

Example solution

The example solution doesn't have to be perfect, but should pass all of the tests and ideally also strive for a healthy balance of human readability and computational efficiency.

Test suite

The test suite should be derived from the respective x-common/exercises/<exercise-name>/canonical-data.json and comply to some formatting and coding standards (to get an idea you can look at some of the existing tests).

Running tests

To run the tests for just a single exercise, run source('test_<exercise-name>.R') from within the exercise's directory. Note that when testing locally you'll need to replace the first line of test_<exercise-name>.R (which sources <exercise-name>.R) with source('example.R'). If you do this, remember to change it back before submitting any pull requests.

Alternatively, to run tests for all exercises at once, simply run source("bin/run_tests.R").

The example solutions must pass the tests without failures. Additionally the tests should not run longer than a few seconds.

In order to be accepted by Travis-CI, each exercise must be registered in config.json.

Style guide

There are a variety of R style guides in circulation and opinions on the topic can vary widely which does make it hard to settle on specific standards. Our preference is to have R code in this repository follow the tidyverse style guide.

You are thus encouraged to run lintr on your R scripts before opening a pull request in order to check that your code adheres to this style guide before submitting it for review.

Note however that at the moment only the following linting rules are strictly enforced:

• line length should be less than 80 characters
• objects should not be in camelCase, snake_case is preferred
• the assignment operator <- should be used
• all commas should be followed by a space (but not preceded by one)
• no absolute paths should be used
• infix operators (+, -, =, <-) should have spaces around them

To perform these specific checks locally, run source("bin/run_lints.R").

R icon

The R logo was created by Hadley Wickham and others at RStudio. The original file is licensed under version 4.0 of the Creative Commons Attribution-Share Alike license. We have adapted it, changing the colour scheme, for use on Exercism.