From c6f874b5fd8d3d3ceb99739acd1dc116bcefd0b3 Mon Sep 17 00:00:00 2001 From: Gipzy8 Date: Wed, 29 Jul 2026 12:58:46 -0600 Subject: [PATCH] docs: add approval readiness checklist for contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a short final checklist covering implementation completeness, testing and CI expectations, acceptance criteria review, and known limitations — including an explicit note that a merged PR is not yet an approved one. Link it from the README documentation index. Closes #537 --- README.md | 1 + docs/approval-readiness-checklist.md | 113 +++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/approval-readiness-checklist.md diff --git a/README.md b/README.md index 8b50688..a9d3b80 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,7 @@ stellar-pocketpay-contracts/ - [Failure Mode Catalogue](docs/failure-mode-catalogue.md) – Summary of safe-failure behavior, expected errors, affected functions, and related tests for vault operations. - [Contributor Security Checklist](docs/security-checklist.md) – Practical review checklist for vault contract changes covering accounting, lock state, token transfer safety, authorisation, storage, events, error handling, and tests. - [Contributor Self-Review Template](docs/self-review-template.md) – Copy-paste checklist covering behaviour, tests, CI, security, edge cases, and docs impact — fill it in before opening a PR. +- [Approval Readiness Checklist](docs/approval-readiness-checklist.md) – Final checklist before requesting evaluation: implementation completeness, tests, CI status, acceptance criteria review, docs, known limitations, and the post-merge-is-not-approval note. - [Traceability Table Guide](docs/traceability-table.md) – Standard format for mapping PR changes to issue acceptance criteria, with worked examples. - [Payment-Period Conduct Guidance](docs/payment-period-conduct.md) – Expectations for how contributors raise payment-status questions, and how GrantFox's evaluation process relates to this repository's review process. diff --git a/docs/approval-readiness-checklist.md b/docs/approval-readiness-checklist.md new file mode 100644 index 0000000..172433e --- /dev/null +++ b/docs/approval-readiness-checklist.md @@ -0,0 +1,113 @@ +# Approval Readiness Checklist + +Use this checklist right before you consider an issue ready for maintainer +evaluation — after your own [Self-Review Template](self-review-template.md) is +filled in, and before you request review or raise a payment-period question. + +Merging a PR does **not** mean the work is approved. This checklist exists so +you catch gaps yourself, but the final call on whether an issue's acceptance +criteria are actually met is a maintainer/GrantFox evaluation step, not the +merge event. + +This is not a new process — it is a short, final pass over checks that already +exist elsewhere in this repo. If an item below fails, follow the linked doc +for how to fix it; don't just note it as a known gap. + +## 1. Implementation completeness + +- [ ] Every acceptance criterion in the linked issue is fully implemented, not + partially — see the [Contribution Quality Gate](contribution-quality-gate.md#1-quality-gate-checklist). +- [ ] No `TODO`, `FIXME`, or `HACK` markers remain in the code this PR touches. +- [ ] The PR is scoped to this issue only — unrelated refactors or fixes are + split into a separate PR. + +## 2. Tests + +- [ ] `cargo test --workspace` passes locally, and the summary (test count) is + pasted into the PR. +- [ ] Every new or changed function has tests for the happy path and for + failure/boundary conditions, following the + [test naming convention](testing.md). +- [ ] Accounting or invariant changes are checked against the + [Invariant Test Checklist](invariant-test-checklist.md) and the property + tests in `contracts/savings_vault/src/test/property_vault_accounting.rs`. +- [ ] Event schema changes have updated snapshots under + `contracts/savings_vault/test_snapshots/`. + +## 3. CI status + +> This repository has no GitHub Actions workflow that builds, lints, or tests +> the contract. The only workflow, `.github/workflows/trigger-auto-merge.yml`, +> dispatches to an external automation repo and does not run `cargo test`, +> Clippy, `fmt`, or a build. "CI status" below means the local commands run +> and reported by you — not a GitHub check. + +- [ ] `make verify` passes locally (`cargo fmt --check`, + `cargo clippy --tests -- -D warnings`, `cargo test --workspace`, + `cargo build --release --target wasm32-unknown-unknown`), and the output + is pasted into the PR — not just asserted. +- [ ] `make build-release` (or `make wasm-size`) output is included, and any + WASM size growth versus the previous release is explained. + +## 4. Acceptance criteria review + +- [ ] The linked issue's acceptance criteria are re-read one by one, and each + is confirmed `Met` or `Deferred` — not assumed from memory of the + original implementation work. +- [ ] The [Acceptance Criteria Audit Table](ACCEPTANCE_CRITERIA_AUDIT.md) is + filled in the PR description, with a file/line reference and a test name + for every row marked `Pass`. +- [ ] Every criterion marked `Deferred` has a written justification and a + linked tracking issue in the PR description. + +## 5. Documentation updated + +- [ ] Behaviour or architectural changes are reflected in the relevant + `docs/` file(s), not only in code comments. +- [ ] If a function was added, removed, or changed, `docs/api-reference.md` + and the README [Features](../README.md#features) table match the new + signature. +- [ ] Event or security-relevant docs are updated when applicable + (`docs/events.md`, `docs/event-schema.md`, `docs/security-checklist.md`). +- [ ] New docs are linked from the README + [Documentation](../README.md#documentation) list, per the + [Documentation Style Guide](docs-style-guide.md#linking-related-docs). + +## 6. Known limitations + +- [ ] Anything left out of scope, deferred, or not fully solved by this PR is + written down explicitly in the PR description — not left implicit or + discovered later by a reviewer. +- [ ] Each known limitation either links a tracking issue or states plainly + that none is planned yet. + +## 7. Merge is not approval + +- [ ] I understand that merging this PR into `main` is not, by itself, an + approval of the work or a confirmation that payment/evaluation criteria + are met. +- [ ] I understand evaluation and payment happen in a separate, post-merge + step run by GrantFox, per the + [Payment-Period Communication Policy](PAYMENT_POLICY.md) and the + [Payment-Period Conduct Guidance](payment-period-conduct.md), and that a + merged PR can still be found incomplete during that review. +- [ ] I have not treated a merge, or the absence of a payment update, as + grounds to escalate or repeat a payment-status question — see + [Payment-Period Conduct Guidance](payment-period-conduct.md#what-to-avoid). + +--- + +## Relationship to other docs + +This checklist doesn't replace anything — it's the last, short pass before you +ask for evaluation, after the longer worksheets below are already done: + +- [Self-Review Template](self-review-template.md) — the detailed, fill-in + worksheet for behaviour, tests, CI, security, and edge cases; do this first. +- [Contribution Quality Gate](contribution-quality-gate.md) — the fuller + narrative definition of "payment-ready" work, with examples of incomplete + PRs. +- [Acceptance Criteria Audit Template](ACCEPTANCE_CRITERIA_AUDIT.md) — the + table format referenced in section 4. +- [Payment-Period Conduct Guidance](payment-period-conduct.md) — what to check + before raising a payment-status question, referenced in section 7.