jared
7cad98b434
Adds pm/compass.toml with five workstreams (theme, logo, quarto, helpers, packaging), the journal and decision-record scaffold, and a composed .roborev.toml carrying nine project-specific review rules derived from the package's actual conventions. Also adds AGENTS.md as the cross-tool conventions file, wires project memory into .agent/memory/ so it travels between machines, and untracks tests/testthat/Rplots.pdf, which churned on every test run.
3.8 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
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.