Project-level instructions for AI coding agents working on this repository. This file records only what the code, DESCRIPTION, Makefile, and the function documentation do not already tell you.
Package overview
ggstatsplot creates ggplot2 plots with statistical details in the plot. It is a visualization frontend for statsExpressions: statistical computation belongs there, and plotting functions here should delegate to it rather than duplicate statistical logic.
grouped_* variants map the corresponding plotting function across a grouping variable and combine the plots with patchwork; follow the existing purrr and patchwork::wrap_plots() pattern. ggcoefstats() has no grouped variant.
Validation gate
The repository prompts and skills refer to this as the full validation gate:
If Air reports drift, run air format . and inspect the result. Run the narrowest relevant test file first, for example Rscript -e 'testthat::test_local(filter = "ggbetweenstats")'. make document only renders README.Rmd; it does not regenerate roxygen output.
Versioning and changelog
- Development versions use a fourth-component
.9000suffix. - Keep the version in
DESCRIPTION,codemeta.json, and the firstNEWS.mdheading synchronized. - Record user-facing compatibility or behavior changes in
NEWS.md; omit routine dependency, formatting, lint, test, CI, and generated-file maintenance.
Testing
tests/testthat.Rruns tests only on Linux and macOS, so there are no Windows snapshot variants.CI requires 100% line and branch coverage (covr’s
covr.branch_coverage), and Codecov requires 100% project and patch coverage. Aswitch()without a default leaves an untaken “no match” branch, so make its last case the default or use a lookup vector.Set seeds before tests that use random or Bayesian computations. Suppress warnings only when a test intentionally exercises a warning-producing path.
Plot output is covered by
vdiffrsnapshots (expect_doppelganger()) intests/testthat/_snaps/. A few usevariant =for platform (darwin/,linux/) or R-version (r-4.7/) differences; add a variant only when the difference is confirmed to be renderer-specific.Treat broad snapshot diffs after dependency updates as likely renderer churn. Compare the old and new dependency builds under the same R and graphics stack; if both reproduce the same SVG changes, restore the repository snapshots rather than committing them. Confirm legitimate baseline updates against the snapshot artifact the R-CMD-check workflow uploads on failure.
Code conventions
- Use the base R pipe (
|>), not%>%, and snake_case names. - Use
@autoglobalfromroxyglobalswhere appropriate.
Roxygen documentation
- After changing roxygen comments, run
Rscript -e 'roxygen2::roxygenise()'and commit the generatedNAMESPACE,man/*.Rd,API(frompkgapi), andR/globals.R(fromroxyglobals). Do not edit generated files by hand. -
pkgapiis not on CRAN; install it withpak::pak("r-lib/pkgapi"). - Regenerate with the roxygen2 release in
Config/roxygen2/version. A newer release rewrites that field and may reformatNAMESPACE; bump it only deliberately, together with the regenerated output. - Several parameters are inherited from
statsExpressionsvia@inheritParams, so generated.Rdtext depends on the installed version. Regenerate against the versionDESCRIPTIONrequires (its GitHub development version while listed underRemotes, otherwise its CRAN release). - Shared documentation lives in fragments; edit the fragment, not the generated output.
man/rmd-fragments/*.Rmdare pulled into function docs with roxygenchild=chunks and intovignettes/web_only/articles withasisfile chunks.man/md-fragments/*.mdare included by vignettes withasisfile chunks. In articles, useasisfile chunks rather thanchild=: pkgdown renders them from a temporary file, so relative child paths do not resolve. The closing sections shared by the articles live invignettes/web_only/_footer.Rmd, which contains R code and is therefore knitted from a chunk withknitr::knit_child(text = readLines(...)).
Repository skills and prompts
Task-specific procedures live in .agents/skills/<name>/SKILL.md. Read one only when the task matches it:
-
create-release: prepare, submit, resume, or publish a CRAN release. -
update-dependencies: update dependencies, change the minimum R version, or add, remove, or move a dependency. -
maintain-ci: change or debug workflows under.github/workflows/.
User-invoked prompts (address-review.md, simplify-codebase.md, and update-deps.md) live in .github/prompts/. Keep each topic in exactly one place: this file for every-session rules, a skill or prompt for task-specific procedures.
Continuous integration
Workflows under .github/workflows/ are thin callers of shared reusable workflows; the maintain-ci skill covers changing them.
- Reference
IndrajeetPatil/workflowsreusable workflows as@main, never a commit SHA. The owner maintains them and is the only person who can contribute to this repository, so there is no external-contributor risk, and@mainkeeps it on the latest version. Code scanners (CodeQLactions/unpinned-tag, zizmorunpinned-uses) flag this by design: do not report it or propose a pin; dismiss such alerts as “won’t fix” with this reason.
Benchmarks
See benchmarks/README.md for API coverage policy, workload catalogue, local execution, and interpretation of CodSpeed results.
Pull requests
Open pull requests as ready for review. Watch CI and review comments after opening and updating a pull request. Fix build failures, address review feedback, and reply to comments; resolve threads once handled. After changes, repeat the checks and request Codex review for the new head. Squash-merge only after all required builds are green and Codex has approved the current head, with no unresolved findings and the reviewed commit matching the head. Because only the repository owner can contribute, a coding agent may use admin privileges to squash-merge when GitHub’s required human approval is the only remaining blocker. Never use admin privileges to bypass builds or Codex approval.
