Overview

Introduction

This section of the website is dedicated to materials you may need when you want to make a contribution to The Carpentries Workbench. It will detail the minimum developer environment required to contribute to the components of this project.

This section is still under construction!

We are still assembling the documentation for this part of the site. If you would like to contribute, please feel free to open an issue.

The core of The Carpentries Workbench consists of three packages:

These packages are all available and released to the Carpentries R-Universe, which checks for updates to the source packages hourly.

If you are interested, we have documentation for the release process available.

Development

Development of The Workbench is overseen by Zhian N. Kamvar. New features are added incrementally as pull requests. Pushes to the main branch are rare and discouraged. New features must have tests associated (with the exception of {varnish}).

Software Tools

Development of Workbench components requires the same toolchain for working on lessons:

  • R
  • pandoc
  • Git

It is recommended to have the latest versions of R and pandoc available. You need at least git 2.28 for security purposes.

R version
---
R version 4.2.2 Patched (2022-11-10 r83330) -- "Innocent and Trusting"
Copyright (C) 2022 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.

pandoc version
---
pandoc 2.19.2
Compiled with pandoc-types 1.22.2.1, texmath 0.12.5.2, skylighting 0.13,
citeproc 0.8.0.1, ipynb 0.2, hslua 2.2.1
Scripting engine: Lua 5.4
User data directory: /home/runner/.local/share/pandoc
Copyright (C) 2006-2022 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

git version
---
git version 2.39.1

Once you have these installed, make sure to install ALL of the dependencies for the workbench:

install.packages(c("sandpaper", "pegboard", "varnish", "tinkr"),
  dependencies = TRUE,
  repos = c(getOption("repos"), "https://carpentries.r-universe.dev"))

In addition, you will need the {devtools} for development.

install.packages("devtools")

Documentation

Reference documentation for individual functions for each package is written alongside the function using {roxygen2}.

This documentation is generated by devtools::document()

Testing

Tests for each package live in tests/testthat/ and follow a test-[file-name].R naming convention. These are controlled by the {testthat} package and run by devtools::test().

Note that {sandpaper} tests take a long time to run and require internet.

Continous Integration

The continous integration for each package tests on Ubuntu, MacOS, and Windows systems with the last five versions of R (same as the RStudio convention).

Coming up:

  • Testing Pull Requests (Locally and on your fork)
  • Resources for R package development
  • Adding functionality to {sandpaper}
  • Adding functionality to {pegboard}
  • Adding styling elements to {varnish}
  • Adding functionality to carpentries/actions