Developer Contribution Guidelines

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. These guidelines prioritise CRAN compliance and long-term stability over rapid feature iteration.

1. Branching & Pull Requests

• Each change (bug fix, new feature, refactor, etc.) should be developed in a dedicated branch.
• Once development is complete:
  1. Run devtools::check() locally with TEST_PROTTI and BUILD_VIGNETTE environment variables set.
  2. Open a Pull Request (PR) into the Developer branch.
  3. All GitHub Actions workflows need to pass (exceptions can be made for tests that fail due to external factors).
  4. At least one reviewer should review the PR before merging.

2. Code Style

• All code should be written using the tidyverse 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 behaviour

• 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

• Document new features clearly.
• Mention any user facing changes in NEWS.
• Write roxygen documentation and update README.Rmd and vignettes if necessary.
• 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 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:

if (!requireNamespace("PackageName", quietly = TRUE)) {
    message(strwrap("Package \"PackageName\" is needed for this function to work. Please install it.",
      prefix = "\n", initial = ""
    ))
    return(invisible(NULL))
  }

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:
  • New versions release
  • 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

• Check NEWS:
  • Are all updates documented?
  • Is the version number correct?
• Check DESCRIPTION:
  • Is the version number correct?
• Run devtools::document() and devtools::build_readme()
• Run Sys.setenv(TEST_PROTTI = "true", BUILD_VIGNETTE = "true")
• Run devtools::check() to test package locally.
• Run devtools::check_mac_release() to test package remotely on Mac.
• Run devtools::check_win_release() to test package remotely on CRAN servers.
  • You may need to fix some links that don't work externally.
• Update cran-comments.md
• Commit any leftover changes.
• Restart R session or set above environment variables to "false".
• Run devtools::release() to submit package to CRAN.
• Confirm submission in email.

After CRAN acceptance:

• Merge Developer → main
• Create a GitHub release for the new version