Skip to contents

Contributing

Source: vignettes/Contributing.Rmd
Contributing.Rmd

To contribute to this package, you should follow the below steps:

  1. Create a issue at github.com/spang-lab/metabodeconplus/issues describing the problem or feature you want to work on.
  2. Wait until the issue is approved by a package maintainer.
  3. Create a fork of the repository at github.com/spang-lab/metabodeconplus
  4. Make your edits as described in section Making Edits
  5. Create a pull request at github.com/spang-lab/metabodeconplus/pulls

Making Edits

Things you can update, are:

  1. Function code in folder R
  2. Function documentation in folder R
  3. Package documentation in folder vignettes
  4. Test cases in folder tests
  5. Dependencies in file DESCRIPTION
  6. Authors in file DESCRIPTION

Whenever you update any of those things, you should run the below commands to check that everything is still working as expected:

devtools::document() # Build files in man folder
devtools::spell_check() # Check spelling (add false positives to inst/WORDLIST)
urlchecker::url_check() # Check URLs
devtools::load_all() # Load the package incl. internal functions
run_tests(all = TRUE) # Execute tests from tests folder incl. slow tests
devtools::run_examples(run_donttest = TRUE) # Run all examples in the package
devtools::check() # Check package formalities
toscutil::check_pkg_docs() # Check function documentation for missing tags
pkgdown::build_site() # Build website in docs folder

run_tests() is an internal helper, so it is only available after devtools::load_all() (or as metabodeconplus:::run_tests() from an installed copy). With all = TRUE it sets the environment variable RUN_SLOW_TESTS=TRUE, which enables the slow tests (e.g. tests that download the example datasets). The same variable can be set manually before calling devtools::test().

Some checks, e.g. tests that run with multiple workers, need the package to be installed. To install it from the repository root, run the following command in a shell:

R CMD INSTALL --no-lock --no-staged-install .

The two flags avoid failures caused by stale 00LOCK-metabodeconplus directories, which can occur if the package’s shared library is still in use by a running R session (e.g. on network file systems).

After doing these steps, you can push your changes to Github and create a pull request.

Releasing to CRAN

Whenever a package maintainer wants to release a new version of the package to CRAN, they should:

  1. Check that all release requirements and CRAN Policies are fulfilled
  2. Use the following commands to do a final check of the package and release it to CRAN
# Check spelling and URLs. False positive findings of spell check should be
# added to inst/WORDLIST.
devtools::spell_check()
urlchecker::url_check()

# Slower, but more realistic tests than normal devtools::check()
devtools::check(
    args = c("--as-cran", "--timings"),
    error_on = ("warning"),
    check_dir = "../metabodeconplus-RCMDcheck",
    remote = TRUE,
    manual = TRUE,
    run_dont_test = TRUE
)

# Check reverse dependencies. For details see:
# https://r-pkgs.org/release.html#sec-release-revdep-checks
pak::pkg_install("r-lib/revdepcheck")
revdepcheck::revdep_check(num_workers = 8) # working again at 2025/09/12

# Send your package to CRAN's builder services. You should receive an e-mail
# within about 30 minutes with a link to the check results. Checking with
# check_win_devel is required by CRAN policy and will (also) be done as part
# of CRAN's incoming checks.
devtools::check_win_oldrelease()
devtools::check_win_release()
devtools::check_win_devel()
devtools::check_mac_release()

# Use the following command to submit the package to CRAN or submit via the web
# interface available at https://cran.r-project.org/submit.html.
devtools::submit_cran()

Release bookkeeping:

  1. Before submitting, bump the version in DESCRIPTION and add a matching entry at the top of NEWS.md.
  2. Update cran-comments.md with the submission type (new release, update or resubmission) and the results of the checks above.
  3. After CRAN has accepted the package, tag the released commit as vX.Y.Z (e.g. git tag v0.22.4 && git push origin v0.22.4) and create a matching GitHub release at github.com/spang-lab/metabodeconplus/releases.