Skip to content

Developer Contribution Guidelines

Jump to bottom
Jan-Philipp Quast edited this page Jan 14, 2026 · 9 revisions

Developer Guidelines (Internal)

This page documents how development of this package works and why certain decisions were made. It is intended for developers and maintainers, not for end users. The focus is on reproducibility, CRAN compliance, and long-term maintainability.

1. Branching & Pull Requests

  • Each change (bug fix, new feature, refactor, etc.) should be developed in a dedicated branch.
  • Once development is complete:
    1. Open a Pull Request (PR) into the Developer branch.
    2. At least one reviewer should review the PR before merging.

2. Code Style

All code must follow tidyverse styling using: styler::tidyverse_style() A GitHub Actions workflow automatically applies this style. Still, try to format code locally before committing.

3. Testing

Unit tests are required for all new functions. Run tests locally before opening a PR. CRAN-specific testing behavior Many functions access external databases or APIs. These tests must not run on CRAN, because: External services may be temporarily unavailable APIs may change Full test execution exceeds CRAN time limits (~45 min) Environment variable: TEST_PROTTI Tests that should not run on CRAN must check: Sys.getenv("TEST_PROTTI") == "true" These tests: Run in GitHub Actions Run locally when the variable is set Are skipped on CRAN

4. Documentation

After making changes, always update documentation: Run roxygen to generate documentation: devtools::document() If you modified README.Rmd, rebuild the README: devtools::build_readme()

5. Dependencies

CRAN strongly discourages packages with many dependencies. General rules Keep external dependencies to a minimum. Prefer base R or existing package dependencies when possible. Imports vs Suggests If a dependency is: Core to package functionality → add to Imports Niche or optional → add to Suggests Handling suggested packages in functions If a function relies on a suggested package: Do not add it to Imports Add it to Suggests in DESCRIPTION At the start of the function, check if the package is installed Provide a clear message if it is missing This allows users to install optional dependencies via: devtools::install_github("jpquast/protti", dependencies = TRUE)

6. GitHub Actions & CI

We use several GitHub Actions workflows to ensure quality: Unit testing (Codecov) Code styling R CMD check Documentation site generation (pkgdown – main branch only) These workflows are mostly generated using usethis, with some project-specific environment variables. ➡️ Keep workflows up to date when: R versions change CRAN policies change GitHub Actions deprecate features

7. Vignettes & Package Size

CRAN enforces strict package size limits. Because this package includes many vignettes, we use conditional builds. Environment variable: BUILD_VIGNETTE Vignettes are only built when: Sys.getenv("BUILD_VIGNETTE") == "true" This keeps CRAN submissions within size limits while still allowing full documentation builds locally and in CI.

8. Pre-release Checklist

Before merging Developer into main:

After CRAN acceptance: Merge Developer → main Create a GitHub release for the new version

9. Final Notes

Follow CRAN policies strictly — they are non-negotiable Prefer clarity and robustness over convenience When in doubt, ask for review early rather than late

Clone this wiki locally