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.
94 lines
4.1 KiB
Markdown
94 lines
4.1 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
|
|
|
|
`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.
|
|
|
|
```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.
|