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.
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# 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.
|
|
|
|
```zsh
|
|
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.
|