diff --git a/README.md b/README.md index 0ccdb4d..25841b8 100644 --- a/README.md +++ b/README.md @@ -148,3 +148,6 @@ PRs submitted to this repository are reviewed against our [Pull Request Reviewer ### Acceptance Criteria Traceability Every PR **must** include an [acceptance criteria traceability table](docs/acceptance-criteria-traceability.md) that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers. +### Issue Approval Readiness +Before considering an issue complete and ready for evaluation or payment review, use the [Issue Approval Readiness Checklist](docs/approval-readiness-checklist.md). This checklist covers implementation completeness, testing expectations, CI status, acceptance criteria review, documentation, and known limitations. Note that **a merged PR is still subject to evaluation** — merge does not automatically confirm reward eligibility or campaign completion. + diff --git a/docs/approval-readiness-checklist.md b/docs/approval-readiness-checklist.md new file mode 100644 index 0000000..7258e86 --- /dev/null +++ b/docs/approval-readiness-checklist.md @@ -0,0 +1,114 @@ +# Aegis SDK Issue Approval Readiness Checklist + +> Use this checklist before considering an issue ready for maintainer evaluation, +> GrantFox campaign evaluation, or payment review. +> +> **A merged pull request is still subject to evaluation.** Merge confirms that a +> maintainer accepted the repository change — it does not automatically prove reward +> eligibility, campaign completion, or payment readiness. + +--- + +## 1. Implementation Completeness + +- [ ] Every behavior described in the issue is addressed in the PR diff. +- [ ] Each acceptance criterion from the linked issue is either satisfied or explicitly deferred with a follow-up issue reference. +- [ ] The PR scope matches the issue — no unrelated refactors, formatting fixes, or feature additions are bundled in. +- [ ] Changed files are listed in the PR description with a short explanation of what each one contributes. +- [ ] No placeholder logic, `TODO` comments, or stub implementations are left behind without a documented follow-up path. + +--- + +## 2. Testing Expectations + +- [ ] Every new or changed runtime behavior has at least one focused unit test covering the happy path. +- [ ] At least one meaningful failure path or edge case is tested for each behavior change. +- [ ] Tests use the `@aegis/sdk/testing` mock client for Soroban/Stellar interactions — live RPC is not required to run the suite. +- [ ] Test descriptions describe the scenario, not just "should work" or "returns a value." +- [ ] Docs-only, metadata-only, and comment-only changes include a written no-test justification in the PR description. +- [ ] `npm run verify` passes locally, or the PR explains why a narrower command (`npm test`, `npm run check`) is sufficient. + +--- + +## 3. CI Status Expectations + +- [ ] All required GitHub Actions checks are green on the PR's head commit. +- [ ] The Node 20 and Node 22 matrix jobs in `.github/workflows/runtime-compatibility.yml` both pass. +- [ ] If any check is failing due to an unrelated external issue (e.g., a flaky network probe), the PR description links to the failing job URL and explains why it is not caused by this change. +- [ ] TypeScript compilation (`npm run build`) succeeds with no errors. +- [ ] Lint and format checks (`npm run lint`, `npm run format`) produce no new violations. +- [ ] Runtime compatibility probes (`npm run test:compat`) pass for all supported environments. + +--- + +## 4. Acceptance Criteria Review + +- [ ] The PR description reproduces every acceptance criterion from the linked issue. +- [ ] Each criterion is individually checked off with the specific file path, test name, or documentation section that satisfies it. +- [ ] An [acceptance criteria traceability table](acceptance-criteria-traceability.md) is included, mapping each criterion to SDK modules, tests, docs, and behaviour verification. +- [ ] Criteria that were out of scope are marked deferred with a reason and a follow-up issue number. +- [ ] No criterion is marked complete based solely on documentation unless the issue explicitly asks for documentation. + +--- + +## 5. Documentation + +- [ ] Public SDK behavior changes are reflected in `docs/api-reference.md` with updated signatures, parameters, return types, and examples. +- [ ] New contributor-facing workflows, processes, or concepts are documented under `docs/`. +- [ ] `README.md` is updated if the change introduces new top-level capabilities or changes the contributor workflow. +- [ ] Deprecated exports use `@deprecated` JSDoc annotations. +- [ ] Links in all modified or newly created docs are valid (no broken internal references). + +--- + +## 6. Known Limitations + +- [ ] Any edge case intentionally excluded from scope is documented in the PR description or as a reviewer note before merge. +- [ ] Compatibility constraints (runtime environments, Stellar network versions, Soroban protocol versions) are listed if relevant. +- [ ] Follow-up issues are opened and linked for work that is deferred rather than silently dropped. + +--- + +## Contributor Self-Review Summary + +Before requesting review, confirm all of the following: + +- [ ] The PR uses `Closes #` in the description, or explains partial scope with `Relates to #`. +- [ ] Acceptance criteria are copied into the PR description and checked one by one. +- [ ] Tests cover the expected behavior and at least one meaningful negative path. +- [ ] `npm run verify` passed locally (or the narrower command is justified). +- [ ] All CI checks are green, or unrelated failures are linked and explained. +- [ ] Known limitations, compatibility notes, and follow-up issues are listed. + +--- + +## Merged Does Not Mean Evaluated + +A merge confirms that a maintainer accepted the repository change. It does **not** automatically prove: + +- Reward eligibility under the current GrantFox campaign. +- Campaign completion or payment readiness. +- That all acceptance criteria were satisfied at review time. + +Evaluation after merge may still consider whether: + +1. The issue was assigned or eligible under campaign rules. +2. The PR closed the issue's acceptance criteria — not just nearby docs or code. +3. Test and CI evidence was present at the time of review. +4. Follow-up fixes were required after merge. +5. Submitted evidence is public, durable, and straightforward to verify. + +**A clean merge history is not a substitute for meeting acceptance criteria.** + +--- + +## Related Documentation + +- [Issue Approval Readiness](issue-approval-readiness.md) — companion checklist with per-area evidence guidelines +- [Pull Request Evidence Checklist](pr-evidence-checklist.md) +- [Pull Request Reviewer Checklist](reviewer-checklist.md) +- [Test-First Contribution Guide](test-first-contribution-guide.md) +- [CI Pass Requirements](ci-pass-requirements.md) +- [Acceptance Criteria Traceability](acceptance-criteria-traceability.md) +- [Verification Command](verification.md) +- [Contributor Evaluation Policy](contributor-evaluation-policy.md)