jared
cd1af67a3a
The exclusion patterns are substring matches, so `chore:` never matched `chore(packaging):`. Because the cadence rule in AGENTS.md mandates the `type(ws):` scope, every chore and docs commit was being reviewed -- job 15 spent a thorough review on a config-only commit. Adds the `chore(` and `docs(` forms. Also names pm/compass.toml as authoritative for the review rules, so the prose copy in AGENTS.md cannot silently drift from the generated .roborev.toml. Raised by roborev job 15.
4.1 KiB
AGENTS.md
civilytics is the house R package for Civilytics Consulting: a ggplot2 brand theme
system, curated palettes, logo composition, Quarto/Typst/Reveal templates, and
data-wrangling helpers for public-sector analysis. It is a library other projects
depend on, so a breaking change here breaks reports that are already published.
Project tracking
This repo is managed with compass. pm/compass.toml
defines the workstreams; pm/JOURNAL.md records sessions; pm/decisions/ holds
numbered, immutable decision records. Ask compass where things stand rather than
reading the config back.
Workstreams (the ws/ label on every issue):
ws/ |
covers |
|---|---|
theme |
R/theme.R, R/colors.R, R/fonts.R — themes, palettes, font loading |
logo |
R/logo.R, R/flextable.R, inst/img/ — logo and branded output |
quarto |
R/quarto.R, inst/quarto/ — HTML, PDF, Typst, Reveal templates |
helpers |
R/utils.R, R/prop_conf.R, R/join_utilities.R, R/db.R, R/notifications.R |
packaging |
DESCRIPTION, NAMESPACE, Makefile, Dockerfile, .gitea/workflows/ |
Commit cadence
One coherent unit per commit, subject line:
type(ws): subject (#N)
type is one of feat, fix, refactor, docs, test, chore, perf, ci.
ws is a workstream id from the table above. #N is the issue, when there is one.
Conventions
pm/compass.toml is authoritative for these rules. Its [roborev] project_guidelines are composed into .roborev.toml, so change them there and
re-run compass rather than editing .roborev.toml by hand. The prose below is the
same rules stated for a human reader; if the two ever disagree, pm/compass.toml
wins.
Dependencies. Base R plus ggplot2 (>= 4.0), grid/gridExtra, png/jpeg, stringr, stringdist, showtext/sysfonts, jsonlite. No tidyverse: no dplyr, purrr, magrittr, tibble, or data.table. Prefer an existing dependency or base R over adding one — this package is installed into other people's environments.
Brand colors live in civilytics_colors and nowhere else. Never write a hex
literal in theme, scale, logo, or table code. (R/flextable.R still carries
off-brand Bootstrap defaults; that is known debt, not a pattern to copy.)
Themes default to a transparent background (paper_bg = FALSE) so plots
composite onto any Quarto, Reveal, or Typst background. Thread ink, paper, and
accent into ggplot2 4.0's base-theme parameters rather than setting element colors
one at a time. ggplot2 >= 4.0 is a hard dependency, so use S7 @ property access on
plot and theme objects, not $.
Naming. New functions are snake_case. The camelCase exports (countCleanr,
dbSafeNames, simpleCap, waldInterval, countDots, countNA, findDots,
nvals) are frozen public API — do not rename them.
Documentation. Roxygen generates both man/ and NAMESPACE. Declare imports
with @importFrom in the roxygen block; never hand-edit NAMESPACE. Every exported
function needs @param for each argument and @return; exported API needs
@examples. Re-run roxygen in the same commit as the code change — compass files
documentation debt when code moves and its man/ pages do not.
Output. User-facing progress goes through message() so callers can suppress it.
No cat() or print() in package code.
Assets. Nothing personal or client-identifying is vendored into inst/ — brand
assets only. Version 0.3.2 removed headshots for exactly this reason.
Testing
testthat edition 3, one file per source file (tests/testthat/test_theme.R etc.).
Tests are self-sufficient: no reliance on state left by an earlier test. New
behaviour needs a test; a bug fix needs a test that fails without the fix.
make check # R CMD check --no-manual against a built tarball
Rscript -e 'devtools::test()'
CI runs R CMD check on rocker/r-ver:4.6 via .gitea/workflows/check.yaml for
every push and PR to master.
Release
Bump Version in DESCRIPTION and add a NEWS.md entry under New features,
Bug fixes, or Internal. NEWS.md is the changelog; compass tracks the work
that led to it, not the release itself.