chore(packaging): initialise compass project tracking
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.
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user