diff --git a/README.md b/README.md index c067e7f..f2b9c92 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,13 @@ React Native Expo wallet for Stellar Testnet. The app aims to feel polished and ## Documentation - [Architecture Readiness Review](./docs/architecture-readiness-review.md) - Feature boundaries, duplicated state, SDK integration blockers, security-sensitive areas, and test gaps +- [Evaluation-Readiness Index](./docs/evaluation-readiness-index.md) - Central index linking all evaluation-readiness requirements, including payment expectations, tests, CI, and reviewer checklists - [Issue Approval Readiness Checklist](./docs/issue-approval-readiness-checklist.md) - Fast pre-approval gate covering implementation completeness, tests, CI status, acceptance criteria, documentation, and known limitations, plus the reminder that a merged PR does not guarantee payment approval - [Evaluation Readiness Checklist](./docs/evaluation-readiness-checklist.md) - GrantFox contributor checklist for mobile issues, including tests, CI, screenshots, acceptance criteria, and the reminder that merge does not guarantee payment approval - [Payment-Period Communication Policy](./docs/payment-period-communication-policy.md) - How contributors should communicate during the payment evaluation period: no spam or pressure, self-review before raising payment concerns, and follow the GrantFox evaluation process - [Self-Review Checklist](./docs/self-review-checklist.md) - Quick checklist to run before opening a PR, covering feature completion, tests, CI, screenshots, and device/emulator verification - [Contributor Self-Assessment](./docs/contributor-self-assessment.md) - Pre-review form for confirming scope, test evidence, CI, documentation, limitations, and acceptance criteria +- [Meaningful Change Threshold Guide](./docs/meaningful-change-threshold-guide.md) - Guide explaining what constitutes a meaningful change and how reviewers should assess PR scope and completeness - [Reviewer Evidence Checklist](./docs/reviewer-evidence-checklist.md) - Maintainer-facing checklist for reviewing whether a PR is complete and evaluation-ready, covering implementation scope, quality, test evidence, CI status, documentation impact, acceptance-criteria verification, and risk - [Storage Guide](./docs/storage.md) - SecureStore vs AsyncStorage - [Test-First Contribution Guide](./docs/test-first-contribution-guide.md) - Required test planning, happy-path and negative-path coverage, no-test justification rules, and local verification commands for mobile PRs diff --git a/docs/evaluation-readiness-index.md b/docs/evaluation-readiness-index.md new file mode 100644 index 0000000..a43ee31 --- /dev/null +++ b/docs/evaluation-readiness-index.md @@ -0,0 +1,10 @@ +# Evaluation-Readiness Index + +This page serves as a central hub linking all evaluation-readiness requirements for the PocketPay Mobile repository. Use these guides and checklists to ensure your contributions meet project standards before and during the evaluation period. + +- **Payment Expectation Guide & Communication Policy**: [Payment-Period Communication Policy](payment-period-communication-policy.md) +- **Testing Standard**: [Test-First Contribution Guide](test-first-contribution-guide.md) +- **CI Guidance**: [CI Pass Requirements Guidance](CI_REQUIREMENTS.md) +- **Acceptance Criteria Audit**: [Issue Approval Readiness Checklist](issue-approval-readiness-checklist.md) +- **Self-Assessment**: [Contributor Self-Assessment](contributor-self-assessment.md) +- **Reviewer Checklist**: [Reviewer Evidence Checklist](reviewer-evidence-checklist.md) diff --git a/docs/meaningful-change-threshold-guide.md b/docs/meaningful-change-threshold-guide.md new file mode 100644 index 0000000..46fa3c9 --- /dev/null +++ b/docs/meaningful-change-threshold-guide.md @@ -0,0 +1,44 @@ +# Meaningful Change Threshold Guide + +When contributing to PocketPay Mobile, we value quality and completeness over mere line count. This guide clarifies what constitutes a meaningful change and helps contributors and reviewers assess whether a pull request sufficiently addresses the issue it aims to solve. + +## Line Count is Not the Only Measure + +A Pull Request (PR) should not be judged solely by how many lines of code are changed. A 5-line change can be highly meaningful if it fixes a critical bug or fully implements a requested feature. Conversely, a 500-line change that consists of auto-generated code, unnecessary refactoring, or incomplete features may not meet the threshold for a meaningful change. + +The primary standard for a meaningful change is **completeness, test coverage, and alignment with the issue requirements**. + +## Small Complete vs. Small Incomplete Changes + +A meaningful change, no matter how small, must be complete. + +### Small but Complete Changes (Meaningful) +* **Targeted Bug Fixes:** Changing a single line to fix a crash or a logical error, accompanied by a test verifying the fix. +* **UI Tweaks:** Updating a color code or padding value to match the design spec exactly, verified across different screen sizes. +* **Documentation Updates:** Adding a missing paragraph to the README that clarifies a setup step that was previously confusing. + +### Small Incomplete Changes (Insufficient) +* **Partial Implementations:** Adding a UI button without wiring it up to the corresponding action or state. +* **Unverified Fixes:** Changing a line of code to "see if it works" without adding a test or providing evidence (e.g., screenshots/videos) that the issue is resolved. +* **Superficial Changes:** Modifying code style, variable names, or adding comments without addressing the core functionality requested in the issue (unless the issue explicitly called for a refactor). + +## Examples of Insufficient Changes + +The following examples typically do not meet the threshold for a meaningful change and may be rejected or require substantial revision: + +1. **"Drive-by" formatting:** PRs that only run a linter or formatter without making functional changes, unless specifically requested in an issue. +2. **Adding dead code:** Introducing new functions or components that are not used anywhere in the application. +3. **Tests without implementation:** Writing a test for a feature, but leaving the feature itself unimplemented (unless part of a coordinated TDD effort). +4. **Addressing only part of the Acceptance Criteria:** An issue asks for an API integration and a UI state update, but the PR only updates the UI to show a hardcoded mock value. + +## Reviewer Assessment Guidance + +Reviewers should use the following guidelines when assessing the scope and meaningfulness of a PR: + +1. **Check Acceptance Criteria:** Does the PR fully satisfy all acceptance criteria listed in the original issue? If not, is there a clear, documented reason why (e.g., agreed-upon scope reduction)? +2. **Verify Completeness:** Is the feature or fix end-to-end? Does it handle edge cases and error states appropriately? +3. **Evaluate Tests:** Does the PR include adequate tests (unit, integration, or UI) to prove the change works and to prevent regressions? +4. **Demand Evidence:** For UI changes, does the PR description include screenshots or videos? For logic changes, are the test results clearly documented? +5. **Quality over Quantity:** Do not reject a PR simply because it is small. Focus on whether the PR solves the underlying problem effectively. + +If a PR is deemed insufficient, reviewers should provide constructive feedback, pointing out exactly which requirements are missing and suggesting how the contributor can expand the PR to meet the meaningful change threshold.