Skip to contents

Contributing to gtsummary

Source: .github/CONTRIBUTING.md

This outlines how to propose a change to gtsummary. AI agents working in this repository should also read AGENTS.md, a condensed summary of these conventions.

Fixing typos

Small typos or grammatical errors in documentation may be edited directly using the GitHub web interface, so long as the changes are made in the source file.

  • YES: you edit a roxygen comment in a .R file below R/.
  • NO: you edit an .Rd file below man/.

Both man/*.Rd and NAMESPACE are generated by roxygen2 — run devtools::document() after changing roxygen comments or exports, and never edit the generated files by hand.

Prerequisites

Before you make a substantial pull request, you should always file an issue and make sure someone from the team agrees that it’s a problem. If you’ve found a bug, create an associated issue and illustrate the bug with a minimal reprex.

Development workflow

Common commands while developing:

# regenerate man/*.Rd and NAMESPACE after editing roxygen or exports
devtools::document()

# run the full test suite
devtools::test()

# run a single test file
testthat::test_file("tests/testthat/test-modify_source_note.R")

# accept intended snapshot changes
testthat::snapshot_accept("modify_source_note")

Notes:

  • Many tests use skip_on_cran(). Set NOT_CRAN=true (or run via devtools::test()) to exercise them.
  • Some test suites require optional packages listed under Suggests (e.g. broom.helpers, survey, flextable, cardx); those tests skip when the package is not installed.

Theme elements and internal data

The valid theme elements recognized by set_gtsummary_theme() and with_gtsummary_theme() are not hard-coded — they are defined in data-raw/gtsummary_theme_elements.csv and compiled into the package as the internal df_theme_elements object stored in R/sysdata.rda.

The CSV columns are deprecated, fn (the function the element applies to), name (the theme-element name users set), argument, eval, desc (description), and example.

To add, update, or delete a theme element:

  1. Edit data-raw/gtsummary_theme_elements.csv — add, change, or remove the relevant row.
  2. Regenerate R/sysdata.rda by sourcing the build script from the repo root (the relative CSV paths depend on it):
source("data-raw/internal_data.R")

This script re-reads the CSV and rewrites R/sysdata.rda via usethis::use_data(..., internal = TRUE, overwrite = TRUE). It also rebuilds the other internal objects (df_add_p_tests, lst_translations, special_char) from their data-raw/ sources, so they may be re-serialized as well.
3. Commit both the edited CSV and the regenerated R/sysdata.rda.
4. If you added or removed an element name, update the themes vignette (vignettes/articles/themes.Rmd) and any affected code under R/.

Never edit R/sysdata.rda by hand — it is a generated artifact.

Code conventions

  • Style. New code should follow the tidyverse style guide. You can use the styler package to apply these styles, but please don’t restyle code that has nothing to do with your PR.
  • Documentation. We use roxygen2 with Markdown syntax.
  • Tests. We use testthat. Contributions with test cases included are easier to accept. Add tests to the existing tests/testthat/test-*.R file for the function you are changing rather than creating a new standalone test file.
  • NEWS. For user-facing changes, add a bullet to the top of NEWS.md below the current development version header describing the change, with links to the relevant issue(s)/PR(s).
  • Namespacing. rlang is imported in full (@import rlang), so its functions are called bare, without a rlang:: prefix (e.g. set_cli_abort_call(), arg_match(), enquo(), .data, %||%). All other packages are called namespaced as pkg::fn() (e.g. dplyr::mutate(), gt::md()).
  • Standalone files. The R/import-standalone-*.R files are vendored copies of tidyverse-style helpers (the rlang/usethis “standalone” pattern) that provide the check_*() input validators and map()/imap(), str_*(), fct_*(), and tibble helpers. Do not edit them by hand — each begins with # Standalone file: do not edit by hand. Refresh or add one with the command in its header, e.g. usethis::use_standalone("insightsengineering/standalone", "checks"). Upstream sources are insightsengineering/standalone and r-lib/rlang; fix bugs upstream, not here.

Pull request process

  • We recommend that you create a Git branch for each pull request (PR).
  • Continuous integration runs on GitHub Actions: R CMD check (current and old-release R), test coverage reported to Codecov, and the pkgdown site build. All workflow checks must pass before a PR is merged; the README badges reflect the current status.
  • Performance-sensitive PRs: if your change may affect package performance, begin the PR title with perf. The “Performance Benchmark” workflow (.github/workflows/benchmark.yaml) only runs when the PR title starts with perf; it compares PR-vs-main timings on representative pipelines and posts a benchmark report as a comment on the PR.
  • When merging, the PR template asks maintainers to use “Squash and merge”.

Code of Conduct

Please note that the gtsummary project is released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.