Skip to contents

Thank you for helping improve dampack. This guide covers how to report problems, how to propose changes, and the conventions the package follows. It applies to DARTH members and outside contributors alike.

By participating, you agree to follow the Code of Conduct.

Reporting a bug or asking for a feature

  • Search the open issues first.
  • For a bug, open an issue with the Bug report template and include a minimal reproducible example. The reprex package makes this easy: reprex::reprex() runs your code in a clean session and formats the output for GitHub. Please include sessionInfo() or sessioninfo::session_info().
  • For a new feature, open an issue with the Feature request template before writing code, so the design can be discussed. Explain the decision-analytic use case: what analysis you are trying to do and what output you expect.

Branches and pull requests

main is the only long-lived branch. It must always pass R CMD check.

  1. Open (or pick) an issue for the change.
  2. Create a short-lived branch from main, named after the issue: <issue number>-<short-description>, for example 203-currency-propagation.
  3. Make focused commits. One pull request (PR) should address one issue.
  4. Open a PR into main and fill in the PR template. Use Closes #<issue> in the description so the issue closes when the PR is merged into main, not before.
  5. A PR is merged after CI passes and at least one other DARTH member approves it. The branch is deleted automatically after merging.

Do not push directly to main, and do not keep long-running integration branches; they are how the package’s history diverged before v1.1.0.

Definition of done

Every PR that changes package code includes:

  • Tests. A bug fix comes with a regression test that fails before the fix and passes after. A new function or argument comes with tests of its results, not only that it runs. Use set.seed() in any test that draws random numbers.
  • Documentation. roxygen2 comments updated, and devtools::document() run so man/ and NAMESPACE are current. New exported functions need @examples that run.
  • A NEWS entry. One bullet in NEWS.md under the development version, ending with the issue number, for example (#203). Mark behavior changes and breaking changes explicitly.
  • A clean check. devtools::check() passes locally with no errors or warnings.

Running the checks locally

# install the development dependencies once
install.packages(c("devtools", "lintr", "covr", "pkgdown"))

devtools::load_all()       # load the package from source
devtools::document()       # regenerate man/ and NAMESPACE from roxygen comments
devtools::test()           # run the tests
devtools::check()          # full R CMD check, as CI and CRAN run it
lintr::lint_package()      # style checks (also run by CI)
covr::report()             # browse test coverage line by line
pkgdown::build_site()      # preview the website locally (output in docs/, not committed)

Coding conventions

Style

  • Follow the tidyverse style guide, with lines of up to 120 characters. The .lintr file defines the exact rules, and CI runs lintr on every PR.
  • Use implicit returns; reserve return() for early exits.
  • Use seq_len(n) or seq_along(x) instead of 1:n or 1:length(x), which misbehave when n is 0.
  • Refer to columns that hold strategy names with df[[name]] or df[, name, drop = FALSE], never df$name or a formula, because strategy names may contain spaces and other characters.

Naming objects inside the package (DARTH coding framework)

Internal objects follow the DARTH naming convention <data type>_<variable type>_<description>, from Alarid-Escudero et al. (2019), “A need for change! A coding framework for improving transparency in decision modeling”, PharmacoEconomics 37(11):1329-1339, doi:10.1007/s40273-019-00837-x.

Data type prefix Variable type prefix
(none) scalar n number
v vector p probability
m matrix r rate
a array u utility
df data frame c cost
dtb data table hr hazard ratio
l list q QALYs

Examples: df_cea, v_wtp, m_nmb, l_psa, n_sim. Either prefix is left out when it does not apply. Note that n_ means “number”, not “scalar”: scalars carry no data type prefix.

A prefix must stay true: an object named m_ must still be a matrix after subsetting (use drop = FALSE).

Exported function names and arguments

Exported function and argument names are part of the public API that users’ scripts depend on. Do not rename them in a minor release. A rename goes through soft deprecation with the lifecycle package: keep the old name working, warn with lifecycle::deprecate_soft(), record it in NEWS.md, and remove it only in the next major version.

New exported functions start with a verb (calculate_, make_, plot_, …), and new arguments follow the names already used elsewhere in the package (psa, wtp, currency, effect_units, txtsize, col).

Files and tests

  • Source files live in R/, one family of functions per file.
  • Each source file has a matching test file in tests/testthat/. Existing test files are named test_<source file>.R; follow that pattern until the test suite is migrated to the test-<source file>.R form that usethis::use_test() creates.
  • Example datasets are documented in R/data_<dataset name>.R.

Releases

The maintainer prepares CRAN releases from main using usethis::use_release_issue() as the checklist. Each release is tagged (vX.Y.Z), published as a GitHub release, and archived on Zenodo.