R project template

This is an attempt to make an R project template, that is not an R package, and that uses some of the recent tools that have been created in the R ecosystem. The template is inspired by the python-project-template by Gemma Danks.

The project features rv for project management and packaging, jarl for linting, and air for formatting, justfile, testthat testing, quarto documentation created with quartrify, .editorconfig, .devcontainer, GitHub Actions CI, and automated semantic releases.

While the template can help you start writing code immediately without having to spend time deciding what tools or conventions to use, the tools and conventions that it introduces are not the default way of doing things in the R world, and there is a question mark if they get adopted in the future or not.

How to use this template

1. 🌱 Create a New Repository on GitHub
   1. Click "Use this template".
   2. Choose “Create a new repository”.
   3. Pick a name for your new project (for example, my-awesome-package).
   4. Clone your new repo locally
2. 🏡 Customise the repository
   1. Rename your package directory cd src; mv package_name my_package
   2. Update rproject.toml with your package name, author, and description, and preferred repository.
   3. Update all references to package_name in:
      • src/package_name/__tests__/
      • docs/
      • release-please-config.json
      • GitHub Actions workflow
      • This README (including badge links)
   4. Update the "package-name" field in release-please-config.json with your package name for automatically bumping the version number in rv.lock (see release-please issue #2561).
   5. Customise this README with a description of your project and planned features.
   6. Clear the CHANGELOG.
   7. Enable automated releases by permitting GitHub Actions to open PRs (Settings -> Actions -> Workflow permissions) and add an initial commit hash to bootstrap the release-please in .release-please-manifest.json.
   8. Enable publishing to GitHub Pages (Settings -> Pages).

🚀 Features

• Modular project directory structure using box.
• README template with badges.
• Packaging and dependency management via rv: rproject.toml.
• Linting via Jarl.
• Formatting via Air.
• Testing framework using testthat.
• Git hooks via prek (linting and formatting).
• CI using GitHub Actions: .github/workflows/ci.yml.
• Docs generated with quartify and rendered as a single Quarto website, deployed to GitHub Pages via GitHub action: .github/workflows/generate-docs.yml.
• Templates for GitHub issues: bug report (01-bug.yml) and feature request (02-feature.yml).
• Template for GitHub pull request: .github/pull_request_template.md.
• Template for documenting architectural decisions: docs/architecture/adr/template.md.
  • ADR to explain the rationale for using ADRs: docs/architecture/adr/001-use-architectural-decision-records.md.
• Release automation via GitHub action from release-please: release-please-config.json.
• Citation metadata, automatically updated for each new release: CITATION.cff.
• EditorConfig configuration for consistent coding style across editors: .editorconfig.

‼️ Limitations

• Test coverage cannot be registered with codecov because it seems the R package covr does not work in this type of project structure.
• pkgdown cannot be used for documentation for the same reason as above.
• devtools::check() does not work because it expects a package structure with a DESCRIPTION file and an R/ directory for source code, which this template does not have.

📦 Installation

Working in a development container

A Dockerfile and configuration in .devcontainer can be used in VSCode or GitHub Codespaces to work in a pre-configured development environment. It uses an R base image and installs Quarto, rv, air, jarl, prek, and just.

To open the project in the container VSCode, you will need to add the Dev Containers extension and download Docker (or Podman -- and configure VSCode to use podman instead of Docker) -- see the VSCode tutorial on devcontainers for more details on using devcontainers. Then run:

Dev Containers: Reopen in Container

Manual installation

1. Install rv
2. optional, if you want to use shortcut commands, install just
3. optional, if you want to use pre-commit hooks, install prek
4. optional, if you want to build the docs site locally, install Quarto
5. Clone and install the project using rv:

git clone https://github.com/novica/r-project-template
cd r-project-template
rv sync

1. Install pre-commit hooks (only needs to be done once): just pre-commit-install

🧪 Common Tasks

Several common tasks have been added as recipes to a justfile in the root of the repository:

    default             # Default recipe (shown when running plain `just`)
    install             # Install dependencies (rv sync)
    update              # Upgrade packages to the latest versions available (rv upgrade)
    lint                # Lint (Jarl check)
    format              # Format (Air format)
    test                # Run testthat
    docs-build          # Build docs (Quartify generates reference qmd, Quarto renders the site)
    pre-commit-install  # Install git hooks (via prek)
    pre-commit          # Run all git hooks (via prek)

📚 Documentation

• Generated with quartify and rendered as a single Quarto website (just docs-build), combining this README, the architecture/ADR docs, and the generated API reference. See ADR-004.

🔄 Releases

Managed by release-please: (conventional commits drive semantic versioning and an autogenerated CHANGELOG). - Configuration: release-please-config.json - Version source: rproject.toml

📂 Project Structure

.
├── src/
│   └── package_name/              # Source package
│       ├── __init__.r
│       └── hello.r                # Example module (replace with real code)
|       └── __tests__/             # Test suite for the example module
|          ├── __init__.r
|          ├── helper-module.r
|          └── test_hello.R
├── data-raw/                       # Raw data used in the project (if applicable)
├── docs/                           # Documentation site (Quarto website, see ADR-004)
│   ├── _quarto.yml                # Hand-authored Quarto website project
│   ├── index.qmd                  # Home page ({{< include ../README.md >}})
│   ├── architecture/               # Hand-written: architecture overview + ADRs
│   │   ├── index.md
│   │   └── adr/
│   ├── reference/                  # Generated by quartify (gitignored, rebuilt by `just docs-build`)
│   └── html/                      # Rendered site output (gitignored; deployed to GitHub Pages)
├── notebooks/                     # Quarto notebooks
│   └── demo.qmd
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                # Lint / test / build
│   │   ├── generate-docs.yml     # Generate and deploy docs
│   │   ├── release-please.yml    # Automated releases
|   |   └── update-citaton-date-released.yml     # Update date-released in CITATION.cff on new release
├── .devcontainer/                 # Dev container configuration
│   ├── devcontainer.json
│   └── Dockerfile
├── rproject.toml                  # Project metadata + dependencies (rv)
├── rv.lock                        # Locked dependency versions (rv)
├── README.md                      # Project overview (you are here)
├── CITATION.cff                   # Citation metadata
├── LICENSE                        # License
├── NEWS.md                        # Generated by release-please (post-release)
├── .pre-commit-config.yaml         # Git hooks configuration (run via prek)
├── .release-please-manifest.json  # Release-please state
├── release-please-config.json     # Release-please configuration
├── justfile                       # justfile containing recipes for common tasks
├── .editorconfig                  # Ensures consistent code style across editors
└── .gitignore

Note that while it is common practice to keep the config files at the root of the repository, and this is what I recommend, it is possible to customise the location of some of them if you prefer (e.g. the path to release-please-config.json [can be specified in the release-please.yml file for the GitHub action] (https://github.com/googleapis/release-please-action?tab=readme-ov-file#advanced-release-configuration).

🤝 Contributing

Use conventional commit messages (feat:, fix:, docs:, etc.). Ensure:

• Lint & format clean
• Tests pass
• Docs build without warnings
• ADR drafted for architecturally significant changes

Suggestions and improvements to this template are very welcome — feel free to open an issue or pull request if you spot something that could be refined, added or removed.

📖 Citation

If used in research, cite via CITATION.cff.

🛡 License

BSD-3-Clause – see LICENSE.

Happy coding! 🚀