Skip to contents

Contributing

Source: CONTRIBUTING.md

This document outlines a rough approach for local setup and contributing to this project.

Local setup

To work with this project locally you will need Git and R installed locally. It is also recommended that you install Docker and VSCode to enable you to utilise the devcontainer setup or edit the code directly via GitHub Codespaces.

Alternatively, you can use conda to manage your R packages; see instructions below.

If you’re unfamiliar with using git why not check out the fantastic Carpentries introductory course.

To get working on this project you will need the devtools package which you can install with the following R command:

# Install devtools from CRAN
install.packages("devtools")

Using conda

You can install R and manage your packages and dependencies using conda (see the open source Miniforge installer here). The file conda-dev-env.yml contains a minimal list of packages (including devtools), allowing you to create an environment with conda:

conda env create -f conda-dev-env.yml

Once you’ve agreed to the installation, you can activate your environment called np-r-env:

conda activate np-r-env

You will now be able to launch an interactive R session from the terminal, or run .R files with the Rscript command.

Development workflow

When working locally you should use the following workflow to help develop the code:

  1. Create a fork of the GitHub repository to create your own personal copy of this repository to which you can push changes to
  2. Locally clone your fork so that you can start working on it
  3. Open an R session
  4. Load devtools with: R library(devtools)
  5. Make a change to the package files
  6. Test this in your R session by running load_all() to load the package (check here for any errors)
  7. Check your changes pass tests by running test()
  8. If your package passes the tests and you’ve updated the appropriate documentation you should now run check() locally to make sure all appropriate roxygen2 files are created/update and any functions you’ve now tagged with @export are exported to NAMESPACE
  9. Commit all the changes from the check() run and push these to GitHub
  10. Open a pull request against the main branch from your development branch. This will trigger a GitHub action that also runs the equivalent of check() to make sure you didn’t miss anything and ensure the package still works against different versions of R.
  11. Once the checks pass on the pull request your changes can be accepted by the maintainer.