Skip to contents

Contributing to hte3

Source: vignettes/contributing.Rmd
contributing.Rmd

This guide covers the standard repo workflow for hte3: local setup, tests, documentation, and pkgdown site generation.

If you want to add a new learner or estimand, read Extending hte3 with Custom Learners first and then come back here for the repo workflow.

Local Setup

The package is developed as a standard R package. The user-facing website in docs/ is generated by pkgdown from README.md, man/, and vignettes/.

The main prerequisites are:

  • an R installation that can build packages
  • package dependencies from DESCRIPTION
  • testthat for the test suite
  • pkgdown and roxygen2 when you are updating docs

Typical Change Loop

For most changes, the development loop is:

  1. Edit the relevant R code, tests, and docs.
  2. Rebuild reference files if roxygen comments changed.
  3. Rebuild the pkgdown site when user-facing docs changed.
  4. Run tests.

The main commands are:

Rscript -e 'devtools::document()'
Rscript -e 'pkgdown::build_site()'
Rscript -e 'testthat::test_local(stop_on_failure = FALSE)'

Documentation Responsibilities

User-facing documentation lives in these layers:

  • README.md for installation and entry-point navigation
  • man/ for help-page level function docs
  • vignettes/ for workflow articles
  • docs/ for generated pkgdown output

Do not hand-edit generated files in docs/. Update the source material and rebuild the site instead.

If you add or rename a vignette, also update _pkgdown.yml so the article navigation stays organized by workflow.

Testing Expectations

At minimum, a contribution should include:

  • targeted tests for the changed behavior
  • validation tests for new error paths
  • documentation updates for user-visible API or workflow changes

For learner changes, include fit/predict tests and method-specific guards. For wrapper changes, include at least one end-to-end test through the public API.

Legacy Paper Reproducibility

The EP-learner paper reproduction is kept in the repository, but it is not part of the main pkgdown workflow. Use the scripts under paper_EPlearner_experiments/ and the frozen install helper:

source("paper_EPlearner_experiments/install_legacy_paper_repro.R")

For the automated smoke check, see inst/legacy/run_smoke.R and the legacy-paper-smoke GitHub Actions workflow.

Release Checks

Before a release or a docs-heavy merge, use the repo checklist in dev/release-checklist.md. The main commands are:

Rscript -e 'pkgdown::build_site()'
Rscript -e 'testthat::test_local(stop_on_failure = FALSE)'
R CMD build .
R CMD check --no-manual hte3_<version>.tar.gz

Review README.md, vignettes/, and the generated docs/ output together before pushing.

Learner Contributions

If your contribution adds a new Lrnr_* class or modifies an existing estimand-specific learner:

  • define the estimand and treatment support clearly
  • add or update tests before exposing it through a wrapper
  • document tuning arguments and default behavior explicitly
  • update the relevant workflow article if the learner is public

Use the extending guide for the learner-specific design contract and promotion checklist.