diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 24d8ad3289..77a63f217e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -46,6 +46,14 @@ and add `verified_end_year` when verified coverage has a defined end. Change the verified year fields only after confirming that parameters and tests cover the stated years. +## Axiom parity + +Every policy change here must also be correct in [rulespec-uk](https://github.com/TheAxiomFoundation/rulespec-uk). That covers a new programme, a parameter or threshold update, an eligibility rule and a bug fix. The shared guide, [Mirror policy changes in Axiom](https://github.com/PolicyEngine/.github/blob/main/CONTRIBUTING.md#mirror-policy-changes-in-axiom), defines the `axiom:` line your PR description needs and what a `queued` issue must contain. UK specifics: + +- National modules live under `uk/`, and council schemes such as council tax reduction live under `uk-/`. Search `main` there before opening a new issue. +- An `encoded-correct` claim names the module and a companion case in its `.test.yaml` that exercises the same situation as your YAML test. +- Use `queued` only when the signed encoder is blocked; record the blocker in the issue. Each billed encoder run requires separate approval. Label `queued` issues `pe-parity`. Reuse your YAML test's externally sourced expected values (legislation.gov.uk, gov.uk guidance, official calculators) as the companion tests; don't copy values computed by policyengine-uk. + ## Repo-specific anti-patterns - **Don't change HF upload destinations** in the `policyengine-uk-data` upload pipeline without explicit authorisation — the private/public split exists to respect the UK Data Service licence. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e69de29bb2..efaaeeb295 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,12 @@ +Fixes # + +## What and why + +## Test plan + +- [ ] For policy changes: YAML tests whose expected values come from an external source (legislation, official guidance, official calculator); otherwise mark not applicable. +- [ ] `make format` +- [ ] Changelog fragment in `changelog.d/` + + +axiom: encoded-correct | encoded | queued | n/a: diff --git a/changelog.d/axiom-parity-guidelines.changed.md b/changelog.d/axiom-parity-guidelines.changed.md new file mode 100644 index 0000000000..519d89dc89 --- /dev/null +++ b/changelog.d/axiom-parity-guidelines.changed.md @@ -0,0 +1 @@ +- Documented that policy changes must be mirrored in Axiom RuleSpec (rulespec-uk), and added a pull request template with the required `axiom:` line. diff --git a/docs/engineering/skills/github-prs.md b/docs/engineering/skills/github-prs.md index 596438aeee..a1ac512107 100644 --- a/docs/engineering/skills/github-prs.md +++ b/docs/engineering/skills/github-prs.md @@ -54,6 +54,27 @@ unless the user or maintainer explicitly asks. The type controls the inferred version bump: `breaking` is major, `added` and `removed` are minor, and other types are patch. +## Required Axiom Line + +Every PR that adds, updates or fixes policy (programmes, parameters, eligibility +rules, bug fixes) must also leave the same provision correct in +[rulespec-uk](https://github.com/TheAxiomFoundation/rulespec-uk). State which of +these applies in one line of the PR description: + +```text +axiom: encoded-correct | encoded | queued | n/a: +``` + +If you are an external contributor and cannot complete the Axiom work, use +`axiom: needed`; a maintainer will follow up. + +Use `queued` only when the signed encoder is blocked; record the blocker in the +issue. Each billed encoder run requires separate approval. A `queued` +rulespec-uk issue must be dispatch-ready and labelled `pe-parity`. It needs the +module path and corpus citation, the verbatim law, the required outputs, and +companion tests from the same external source as the PR's YAML tests. Never +hand-write RuleSpec. See `.github/CONTRIBUTING.md` ("Axiom parity"). + ## Required Lint And Format Run lint and formatting before committing. The default command is: