Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (36 loc) · 3.38 KB

AGENTS.md

File metadata and controls

38 lines (36 loc) · 3.38 KB

Red Agent Guide

  • Dependencies: Raku >= 2022.07. Install deps: zef install --/test --test-depends --deps-only ..
  • Run all tests: prove6 -lj8 t (CI uses this). Alt: zef test . --verbose.
  • Run a single test file: prove6 -lv t/35-create.rakutest (replace with target file).
  • Quick compile check (lint): raku -c lib/Red.rakumod and for any changed files.
  • Install locally: zef install --/test .. Generate docs: make docs or raku tools/make-docs.raku.
  • DB config for tests/examples: set RED_DATABASE (e.g. Pg host=localhost ...); many tests work with SQLite by default.
  • Imports: prefer explicit use; examples use use Red:api<2>; internal modules as use Red::....
  • Formatting: 4-space indent, no tabs, trim trailing spaces, ~100 char lines, one statement per line.
  • Types: add type constraints on attributes/signatures (Int, Str, Bool, DateTime, etc.); use is rw only when mutation is required.
  • Naming: Types/Models CamelCase; methods/attributes kebab-case (e.g., create-table, author-id); SQL/table/column names snake_case.
  • Errors: throw typed exceptions (X::Red::*) instead of generic die; use CATCH { default { ... } } to transform/rethrow; avoid silent Nil—return Failure or throw.
  • ORM traits: columns via is column, ids via is serial/is id, FKs via is referencing{ ... }, relations via is relationship{ ... }; keep inflate/deflate pure.
  • Immutability: prefer immutable updates; call .^save explicitly for persistence.
  • Tests: place under t/ as .rakutest; avoid external state; prefer temp SQLite unless RED_DATABASE is required.
  • CI reference: see .github/workflows/matrix.yaml (Raku setup, deps, prove6). Replicate locally when debugging.
  • Docs: make clean-docs then make docs to refresh API docs.
  • Cursor/Copilot: none present (.cursor/rules/, .cursorrules, and .github/copilot-instructions.md not found).
  • Commits: keep diffs minimal and focused; match existing patterns and avoid unrelated formatting changes.

Project Links

Release to Zef

  • Prereqs: zef install App::Mi6 fez; ensure dist.ini has [UploadToZef] and META6.json has auth like zef:FCO.
  • Login: fez login (stores token) or set FEZ_TOKEN environment variable.
  • Verify: tests green (prove6 -lj8 t or zef test .); rebuild docs if needed (make docs).
  • Prepare: update Changes under {{$NEXT}} with notes; keep the format consistent with prior entries.
  • Bump + release (preferred): mi6 release --bump patch (or minor/major). This updates META6.json and Changes, creates and pushes a git tag, then uploads to the Zef ecosystem via Fez (because [UploadToZef] is enabled).
  • Manual alternative: bump META6.json and Changes, commit and tag; mi6 build; then fez upload from the repo root.
  • Verify: after a few minutes, zef search Red or check the Zef index; consumers can zef install Red:ver<NEW>.
  • Troubleshooting: if upload/auth fails, rerun fez login; ensure the version is new and the git tree is clean; make sure the tarball includes META6.json and README (generated by ReadmeFromPod during build).