diff --git a/docs/contribution-quality-gate.md b/docs/contribution-quality-gate.md new file mode 100644 index 0000000..414e6a0 --- /dev/null +++ b/docs/contribution-quality-gate.md @@ -0,0 +1,62 @@ +# Contribution Quality Gate + +This document defines the objective criteria for "payment-ready" or "production-ready" work in the PocketPay Contracts repository. To maintain high security and reliability, every Pull Request (PR) must pass through this quality gate before being considered for final approval. + +## 1. Quality Gate Checklist + +Every PR must satisfy the following checklist. If any item is missing or incomplete, the PR will be flagged for further work. + +### Implementation +- [ ] **Completeness**: The feature or fix is fully implemented according to the issue description. +- [ ] **No Placeholders**: All `TODO`, `FIXME`, and `HACK` comments related to the change have been resolved. +- [ ] **Storage Integrity**: Storage usage follows the [Storage Audit Map](storage-audit.md) and correctly manages Persistent vs. Instance storage. +- [ ] **Authorization**: All state-changing functions correctly enforce `require_auth()` for the appropriate parties. +- [ ] **Error Handling**: Uses structured `ContractError` codes instead of generic panics where appropriate. + +### Testing +- [ ] **Unit Tests**: Every new or modified function has unit tests for both success paths and failure paths (e.g., unauthorized access, invalid inputs). +- [ ] **Invariant Verification**: Changes to accounting logic are verified by new or existing [Property Tests](../contracts/savings_vault/src/test/property_vault_accounting.rs). +- [ ] **Event Snapshots**: Any changes to event schemas have updated [Snapshots](../contracts/savings_vault/test_snapshots/). +- [ ] **Local Verification**: All tests pass locally using `cargo test`. + +### Documentation +- [ ] **README/Docs**: New features or architectural changes are documented in the relevant `docs/` files. +- [ ] **Acceptance Criteria**: The PR description explicitly lists how each Acceptance Criterion from the original issue was met. + +### CI & Tooling +- [ ] **Formatting**: Code is formatted via `cargo fmt`. +- [ ] **Lints**: `cargo clippy --tests` passes with no warnings. +- [ ] **Build**: `make build-release` succeeds and the WASM size remains within acceptable limits. + +--- + +## 2. Contract-Specific Testing Expectations + +Soroban smart contracts require rigorous testing due to their immutable nature once deployed. We expect: + +1. **Authorization Boundaries**: Tests must explicitly verify that a function fails when called by an unauthorized address. +2. **State Rollbacks**: Tests must verify that if a transaction fails (e.g., token transfer failure), no storage mutations occur. +3. **Maturity Checks**: For time-locked funds, tests must verify behavior exactly at, before, and after the maturity timestamp. +4. **Edge Case Amounts**: Test with `0`, `1`, `MAX`, and amounts just below/above configured limits. + +--- + +## 3. Examples of Incomplete Work + +To avoid common pitfalls, here are examples of PRs that do **not** pass the quality gate: + +- **"Happy Path Only"**: A PR that adds a `deposit` feature but only tests a successful deposit, skipping unauthorized or over-limit tests. +- **"Logic without Invariants"**: A PR that changes how balances are calculated but doesn't update the property-based tests that ensure total funds remain constant. +- **"Stale Docs"**: A PR that changes a function signature in the contract but leaves the `api-reference.md` or `README.md` outdated. +- **"Ignoring Clippy"**: A PR where `cargo clippy` emits warnings that the contributor describes as "unrelated" or "minor". +- **"WIP in Main"**: PRs marked as "Work In Progress" or containing half-implemented logic should not be requested for final review. + +--- + +## 4. How to Use This Gate + +1. **Before Opening a PR**: Review your work against this checklist. +2. **In Your PR Description**: Reference this quality gate and confirm that all items are checked. +3. **Reviewers**: Use this checklist as the primary framework for your review. If the gate isn't met, request changes immediately. + +For more details on local reproduction of tests, see the [Test Reproduction Guide](reproducing-test-failures.md).