Development¶

Setup¶

git clone https://github.com/DiogoRibeiro7/heteroTests
cd heteroTests
./setup.sh                      # Debian-based systems: R, renv and the dependencies
Rscript scripts/setup_helper.R  # Windows and macOS

The package locks its dependencies with renv; renv::restore() is the manual alternative to the setup scripts. Fork the repository and create feature branches from main.

Checks¶

Before a pull request, run the checks CI runs:

Command	What it enforces
`Rscript scripts/run_checks.R`	Styles `R/` with styler, lints it, runs the test suite and writes a coverage report to `coverage/index.html`
`lintr::lint_package()`	The rules in `.lintr`: the lintr defaults with a 100-column limit
`spelling::spell_check_package(vignettes = TRUE)`	Spelling; accepted words live in `inst/WORDLIST`
`R CMD check --no-manual`	Everything `R CMD check` finds, with no unchecked warnings or notes

Statistical tests assert behaviour: size, power, and agreement with reference implementations such as lmtest and car, not just the structure of a result. Add unit tests for any new functionality.

Code¶

All R source lives directly in R/, one file per diagnostic, named after the function it defines (R/performBPTest.R), with no subdirectories. Code follows the tidyverse style guide and CRAN policies. A new test follows the conventions: it takes (model, data, ...), returns an htest with the fields What every test returns lists, and refuses the inputs every test refuses.

The tests that guard the public interface name every export: tests/testthat/test-public-api.R lists the exports planned for 1.0.0, so a new export fails it until it is added to the plan, and tests/testthat/test-return-contract.R runs every exported test against the documented fields, from a recipe in tests/testthat/helper-test-recipes.R.

Help pages, and a warning about roxygen2¶

man/ is mixed: 52 of its 133 pages are written by hand and roxygen2 generates the rest. roxygen2 skips an .Rd file that lacks its Generated by roxygen2 header, so the hand-written pages survive a roxygen2::roxygenise() run, but the run re-splits topics that the hand-written pages group on purpose (ht_logging.Rd documents the whole ht_* logging family). Do not run it as part of an unrelated change.

When you change a function signature, update its .Rd file in the same commit: nothing regenerates a hand-written page. tests/testthat/test-documentation-consistency.R runs tools::codoc(), tools::checkDocFiles() and tools::undoc(), so the local test suite catches a mismatch before CI does.

Documentation site¶

This site is built with Material for MkDocs from docs/. Three kinds of pages come from the package itself, and each starts with a comment that names the script that wrote it:

Pages	Written by	From
The API reference, `docs/reference/`, and its part of the nav in `mkdocs.yml`	`tools/build-docs.R`	The help pages in `man/`, grouped by `tools/reference-index.R`
Releases and Roadmap, `docs/releases.md` and `docs/roadmap.md`	`tools/build-docs.R`	`NEWS.md` and `ROADMAP.md`
The user guide, `docs/guide/`	`tools/render-guides.R`	The vignettes, knitted with the package installed from the checkout

The other pages, this one included, are written by hand.

Rscript tools/build-docs.R      # after changing man/, NEWS.md or ROADMAP.md
Rscript tools/render-guides.R   # after changing a vignette
pip install -r docs/requirements.txt
mkdocs serve                    # preview at http://127.0.0.1:8000
mkdocs build --strict           # what CI runs

tools/build-docs.R stops if a help topic is in no section of tools/reference-index.R, and tests/testthat/test-reference-index.R checks that every export is in one, so a new help page has to be placed in a section on purpose. CI runs tools/build-docs.R again and fails if the committed pages differ, then builds the site with --strict, so a broken link or a stale page fails the build. It does not run tools/render-guides.R, which runs the package's code and draws figures whose bytes differ between platforms: commit the guide pages it writes along with the vignette that changed.

Continuous integration¶

Workflow	Runs
`R-CMD-check.yml`	`R CMD check` on Ubuntu (R devel, release and the previous release), macOS and Windows, and with the hard dependencies on R 4.1; weekly or on demand, `--as-cran` and reverse-dependency checks.
`run-checks.yml`	`scripts/run_checks.R`, with coverage sent to Codecov, then the spelling check and a link check whose result is reported, not gated.
`docs.yml`	Regenerates the reference, releases and roadmap pages, fails if the committed ones are out of date, builds the site with `--strict`, and deploys it to GitHub Pages from `main`.
`release.yml`	On a push to `main` whose `DESCRIPTION` version has no tag: builds the tarball, checks it with `R CMD check --as-cran`, tags `v<version>`, publishes a GitHub release with the tarball, and stores the tarball in `cran/`.

A change to Version: in DESCRIPTION therefore starts a release when it reaches main; leave it alone in an ordinary pull request, and add the change to the Development version section at the top of NEWS.md.

Contributing¶

CONTRIBUTING.md covers the rest of what a pull request needs. Open an issue to discuss a substantial change before starting it, and give a pull request a concise description that references the issues it addresses.