Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (66 loc) · 4.15 KB

CLAUDE.md

File metadata and controls

84 lines (66 loc) · 4.15 KB
Raw

Claude Code Instructions

Project guidance for Claude Code (CLI, IDE, and the GitHub Action). The same conventions apply to GitHub Copilot — see .github/copilot-instructions.md, which is the source of truth for repository-specific style and workflow. This file is a short orientation; defer to copilot-instructions.md for details.

Project context

This is a template repository for creating R packages following UCD-SERG standards. When you create a package from it, replace the placeholder package name, Title, and Description in DESCRIPTION (and the project context above) with your actual package details.

Authoritative style guide: UCD-SERG Lab Manual (source: https://github.com/UCD-SERG/lab-manual).

Repository layout

  • R/, man/, NAMESPACE, DESCRIPTION — R package source and generated docs
  • tests/testthat/ — testthat suite (use snapshot tests where helpful)
  • vignettes/ — package vignettes and .qmd articles
  • altdoc/ — altdoc + Quarto documentation site config (quarto_website.yml, index.qmd, post-render scripts)
  • data-raw/ — scripts that generate package data
  • inst/WORDLIST — accepted spell-check terms
  • .github/workflows/ — CI workflow definitions

Documentation build notes

This template documents the package with altdoc

  • Quarto (not pkgdown):
  • altdoc::render_docs() generates man-page .qmd files (under altdoc/man/) from man/*.Rd at build time, then invokes Quarto (project root altdoc/, altdoc/quarto_website.yml) to render the site into docs/. The docs/ output is gitignored; the generated man .qmd files are regenerated each build — neither is committed.
  • For doc or vignette changes, build and preview locally before requesting review: altdoc::render_docs(verbose = TRUE), then altdoc::preview_docs(), and visually confirm the rendered site (math, code highlighting, links, nav).
  • .github/workflows/docs.yaml builds and deploys the site: pushes to main go to /dev/, stable releases go to /latest-tag/ and /<tag>/, and each PR gets a preview at /preview/pr<number>/ via rossjrw/pr-preview-action. A Versions navbar dropdown is generated by .github/scripts/generate_version_dropdown.py.

Pre-commit checklist

Run the relevant checks before committing (see copilot-instructions.md for the full list). Slash commands are available for the common ones:

  • /document — devtools::document() after editing roxygen2 comments (keeps man/, NAMESPACE, DESCRIPTION in sync; R-check-docs.yml enforces this).
  • /lint — lintr::lint_package() against .lintr.R; fix issues in changed files.
  • /spell — spelling::spell_check_package(); add genuine terms to inst/WORDLIST.
  • /test — devtools::test() for affected tests.
  • /check — devtools::check() for the full R CMD check (slow).
  • Add a NEWS.md bullet for any user-facing change (news.yaml enforces this via UCD-SERG/changelog-check-action).

Working in this repo

  • Don't remove features as workarounds. If a link, button, or behavior is broken, fix the root cause. Only remove or disable a feature when explicitly instructed to.
  • Don't edit generated files: README.md is built from README.Rmd; man/ and NAMESPACE are generated by devtools::document().
  • Style: respect .lintr.R (snake_case, line length, etc.). Extract complex argument validation into internal helpers (e.g. .validate_*()).
  • Tests: cover new/changed behavior with testthat; set seeds where randomness is involved so snapshots are deterministic.

Pull request expectations

  • Keep PRs scoped — bug fixes shouldn't smuggle in refactors.
  • Write commit messages and PR descriptions explaining the why, not the what.
  • Don't bypass CI failures (spell check, lint, docs sync) — fix the underlying issue.

Things to avoid

  • Adding new package dependencies without a clear reason; declare them in DESCRIPTION (Imports/Suggests) rather than loading ad hoc.
  • Reformatting unrelated files.
  • Inventing URLs or citations — only use sources explicitly provided.