Skip to contents

Contributing to chapr

Source: CONTRIBUTING.md

Thank you for your interest in contributing to the Chap R SDK! This document provides guidelines and instructions for contributing.

Code of Conduct

Please read and follow our Code of Conduct.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub with:

  1. A clear, descriptive title
  2. A detailed description of the problem
  3. Steps to reproduce the issue
  4. Expected behavior vs. actual behavior
  5. Your R version and operating system
  6. Any relevant error messages or logs

Suggesting Features

Feature suggestions are welcome! Please open an issue with:

  1. A clear description of the feature
  2. The use case or problem it solves
  3. Any implementation ideas you might have

Pull Requests

  1. Fork the repository
  2. Create a new branch for your feature or fix (git checkout -b feature/your-feature-name)
  3. Make your changes
  4. Ensure all tests pass (devtools::test())
  5. Run devtools::check() and address any issues
  6. Submit a pull request

Development Setup

This project uses renv for reproducible dependency management.

Prerequisites

  • R (>= 4.0.0)
  • RStudio (recommended) or another R IDE
  • devtools package

Getting Started

# Clone the repository
git clone https://github.com/dhis2-chap/chap_r_sdk.git
cd chap_r_sdk

In R:

# Restore dependencies via renv
renv::restore()

# Load the package for development
devtools::load_all()

Working with Model Examples

Each example in examples/ has its own isolated renv environment:

cd examples/fable_model
Rscript -e 'renv::restore()'

Development Workflow

# Load package during development
devtools::load_all()

# Run tests
devtools::test()

# Run a single test file
devtools::test_active_file()  # In RStudio
testthat::test_file("tests/testthat/test-validation.R")

# Generate documentation
devtools::document()

# Run R CMD check
devtools::check()

# Build vignettes
devtools::build_vignettes()

Coding Standards

Style Guide

We follow the tidyverse style guide. Key points:

  • Use snake_case for function and variable names
  • Use meaningful, descriptive names
  • Keep lines under 80 characters when possible
  • Use <- for assignment, not =

Documentation

  • All exported functions must have roxygen2 documentation
  • Include @param, @return, @export, and @examples sections
  • Examples should be runnable or wrapped in \dontrun{}

Example:

#' Brief description of the function
#'
#' Longer description if needed.
#'
#' @param x Description of parameter x
#' @param y Description of parameter y
#'
#' @return Description of what the function returns
#'
#' @export
#'
#' @examples
#' my_function(1, 2)
my_function <- function(x, y) {
  # Implementation
}

Testing

  • Write tests for all new functionality
  • Place tests in tests/testthat/
  • Follow the naming convention: test-{source-file-name}.R
  • Use descriptive test names

Example:

test_that("function_name handles edge case correctly", {
  result <- function_name(edge_case_input)
  expect_equal(result, expected_output)
})

Project Structure

chap_r_sdk/
├── R/                    # R source files
│   ├── cli.R             # CLI interface functions
│   ├── validation.R      # Model validation functions
│   ├── config.R          # Configuration management
│   └── ...
├── man/                  # Generated documentation (do not edit)
├── tests/
│   └── testthat/         # Test files
├── vignettes/            # Long-form documentation
├── inst/
│   └── testdata/         # Test data files
├── examples/             # Example model implementations
├── DESCRIPTION           # Package metadata
└── NAMESPACE             # Exports (generated by roxygen2)

Pre-Push Checklist

Before pushing your changes:

  1. Run devtools::test() - all tests should pass
  2. Run devtools::check() - address all errors and warnings
  3. Run devtools::document() - update documentation
  4. Run spelling::spell_check_package() - fix any spelling errors
  5. Update NEWS.md if adding user-facing changes

Getting Help

  • Open an issue on GitHub for questions
  • Check existing issues and documentation first
  • Provide context and reproducible examples when asking for help

License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.