Skip to contents

Contributing to hestia

Source: CONTRIBUTING.md

Thank you for your interest in contributing to hestia! This document explains how to report issues, propose changes, and what to expect from the CI pipeline when you open a pull request.

Code of Conduct

All contributors are expected to be respectful and professional in all interactions — issues, pull requests, code reviews, and discussions. Constructive feedback is welcome; personal attacks and dismissive language are not.

Reporting Bugs

Use the bug report template when opening a new issue. It asks for a description, a minimal reprex, your sessionInfo() output, and your operating system.

Suggesting Features

Use the feature request template. Describe the use case and, if possible, how the feature fits into the existing model workflow (make_infection_model() -> run_model() -> post-processing). You can also open a blank issue if neither template fits.

Submitting Changes

  1. Fork & branch. Create a feature branch off main (e.g. fix/split-check or feature/missing-outcomes).
  2. Make your changes. Follow the style conventions below.
  3. Format & lint. Run just format and just lint.
  4. Test locally. Run just test or just test-fast before pushing.
  5. Open a pull request against main with a clear description of what changed and why.

Local Development Commands (just)

We use just to automate common development workflows:

# Format R code using air
just format

# Lint R code using air and lintr
just lint

# Regenerate documentation (man/*.Rd, R/globals.R)
just docs

# Run the test suite
just test

# Run tests stopping on first failure
just test-fast

# Check test coverage via covr
just coverage

# Check spelling
just spell

# Build and check package source tarball
just build
just check-cran

# Build pkgdown site and preview locally
just site
just site-preview

Style & Guidelines

  • R code is formatted with air and linted with lintr (configuration in .lintr).
  • Do not hand-edit generated files: R/stanmodels.R, R/globals.R, src/stanExports_*.{cc,h}, configure, and configure.win are all produced by tooling. The man/*.Rd help pages are regenerated by just docs from roxygen comments in CI, so edit the roxygen, not the .Rd. src/RcppExports.cpp is generated by Rcpp::compileAttributes() and is tracked in git so direct GitHub installations (devtools::install_github()) succeed without requiring local code generation; synchronization is verified automatically by just check-rcpp and unit tests.
  • See AGENTS.md for full developer and AI coding conventions.

What Happens When You Open a PR

Every pull request triggers these GitHub Actions workflows:

Workflow What it does
R-CMD-check Runs a fast Linux prep job to build docs and artifacts once, followed by R CMD check --as-cran across Ubuntu, macOS, and Windows on R release, oldrel, and devel (9 matrix jobs). Stan compilation artifacts are cached per OS and R version.
lint Checks code formatting with air and runs lintr::lint_package().
test-coverage Runs the test suite under covr and uploads coverage to Codecov.
pkgdown Builds the documentation site. On PRs this is a build-only check (no deployment); the site is deployed to GitHub Pages on pushes to main, published releases, and manual workflow dispatches.

These workflows should pass before a PR is merged.

Questions?

If something is unclear, open an issue or comment on an existing one — we are happy to help.