Developer Manual

This vignette contains information on how to set-up the package in order to contribute to the codebase. It also contains information on how to Maintain and Test the package.

Developer Installation

If you want to develop the package, you may want to consider cloning the repository and following the steps below to have the correct environment to improve the package. First, install the crvsreportpackage from GitHub, then ensure all package dependencies are correctly managed and installed using renv:

1) Clone the repository:

git clone https://github.com/tech-acs/crvsreportpackage.git
cd crvsreportpackage

2) Initialize the `renv` environment: Upon first entering the package directory,

renv will activate the specific package environment defined for crvsreportpackage. You need to run the following R commands to restore the required packages:

install.packages("renv")
renv::restore()

This will read the renv.lock file which contains the dependencies and install the correct versions of all required packages.

3) Once the environment is set up, you can install the package using:

devtools::install()

By following these steps, you will ensure that you have all the necessary dependencies and the correct versions installed, allowing crvsreportpackage to function as intended. It will also mean you can now open the project and develop the package further.

Maintenance

Once you have made significant changes to the package, there are several steps that you will need to do:

Run the tests
Make sure documentation (like code structure and other web docs) are updated
Increase the package version. In the DESCRIPTION file, bump-up the Version variable.
Update the automated materials using the instructions below:

# Remove the installed version of the package
remove.packages("crvsreportpackage")

# Clear your R environment
rm(list = ls())

# Restart R session (do this manually or with RStudio shortcut Ctrl+Shift+F10)

# Initialize renv if not already done
if (!"renv" %in% installed.packages()) {
  install.packages("renv")
}
library(renv)

# Restore the environment
renv::restore()

# Update the lockfile
renv::snapshot()

# Recreate documentation and rebuild the package
library(devtools)
document()  # Generates the NAMESPACE file and documentation using roxygen2
build()     # Builds the package
install()   # Installs the package

After these steps the package should be installed with the latest changes to the functions. This should mean the package is in the right state to be updated on the online repo.

Testing

Before you push any changes, double check that all the unit test are working as expected, by running them manually:

testthat::test_dir("tests/testthat")

Codebase Structure

The repository contains a lot more than just some functions. Understanding what each folder or section does is important in order to make changes in the future or to triage any potential issues that may emerge. The diagram below gives some information on the codebase structure:

📦crvsreportpackage 
┣ 📂.github                           # Contains instructions for GitHub
┃ ┣ 📂workflows                       # Contains workflows for GitHub Actions
┃ ┃ ┣ 📜R-CMD-chek.yml                # Automatically runs the tests
┃ ┃ ┗ 📜pkgdown.yaml                  # Automatically builds the website
┃ ┗ 📜PULL_REQUEST_TEMPLATE.md        # Adds a checklist for new Pull Requests
┣ 📂R                                 # Contains the R functions
┣ 📂docs                              # AUTOMATED documents built for the web
┣ 📂inst                              # Contains the sample data
┣ 📂man                               # AUTOMATED information on R functions
┣ 📂renv                              # AUTOMATED information on dependencies 
┣ 📂scripts                           # Contains useful scripts for maintenance
┃ ┣ 📜create_test_data.R              # Will generate synthetic data
┃ ┗ 📜update_description.R            # Will update the description and dependencies
┣ 📂tests                             # Contains the tests for the R folder
┣ 📂vignettes                         # Contains the explanatory articles
┣ 📜.Rbuildignore                     # Contains exceptions for package build
┣ 📜.Rprofile                         # Contains instructions for dependencies
┣ 📜.gitignore                        # Handles exceptions to GitHub upload
┣ 📜CODE_OF_CONDUCT.md                # Information on how to behave
┣ 📜CONTRIBUTING.md                   # Guidance on how to contribute to the code
┣ 📜DESCRIPTION                       # Metadata for the package
┣ 📜LICENSE                           # AUTOMATED package conditions of use
┣ 📜LICENSE.md                        # Detailed package conditions of use
┣ 📜NAMESPACE                         # AUTOMATED details of package functions
┣ 📜README.md                         # Introduction article on the package
┣ 📜_pkgdown.yml                      # Structure of the website
┣ 📜crvsreportpackage.Rproj           # AUTOMATED set-up for R Project
┗ 📜renv.lock                         # AUTOMATED information on dependencies

Function Types

In the package functions can be split into several types. Each type is identified by their start, usually with verb that informs what the function goal is. These are:

contruct_: These will construct a new variable or data for analysis.
create_: These will create a table by taking some data.
handle_: These will handle some of the adjacent processes.
plot_: These will help with the visualisation of the tables or data.

Developer Manual