From 2c511dd5ad60a1756cbd2ef32228573c130a6dbc Mon Sep 17 00:00:00 2001 From: Bot Date: Fri, 26 Jun 2026 23:52:03 +0100 Subject: [PATCH] docs: add governance and testing standards Resolves #772 Resolves #770 Resolves #767 Resolves #766 --- docs/CROSS_REPO_INTEGRATION_TESTS.md | 29 +++++++++++++++++++ docs/DEFINITION_OF_DONE.md | 43 ++++++++++++++++++++++++++++ docs/ISSUE_TAXONOMY_AND_LABELS.md | 41 ++++++++++++++++++++++++++ docs/QUALITY_GATES_MATRIX.md | 37 ++++++++++++++++++++++++ 4 files changed, 150 insertions(+) create mode 100644 docs/CROSS_REPO_INTEGRATION_TESTS.md create mode 100644 docs/DEFINITION_OF_DONE.md create mode 100644 docs/ISSUE_TAXONOMY_AND_LABELS.md create mode 100644 docs/QUALITY_GATES_MATRIX.md diff --git a/docs/CROSS_REPO_INTEGRATION_TESTS.md b/docs/CROSS_REPO_INTEGRATION_TESTS.md new file mode 100644 index 00000000..cb3a1f18 --- /dev/null +++ b/docs/CROSS_REPO_INTEGRATION_TESTS.md @@ -0,0 +1,29 @@ +# Cross-Repo Integration Test Ownership and Coordination Model + +This document defines the ownership, coordination, and workflow for integration tests that span multiple repositories and services within the YieldVault-RWA ecosystem. + +## 1. Ownership Model + +Given that integration tests touch multiple services, clear ownership is required to avoid abandoned tests and broken builds. + +- **Primary Owner (Initiator):** The team or developer that originates the feature requiring cross-repo coordination is the primary owner of the integration test. They are responsible for writing, maintaining, and debugging the test in the first instance. +- **Secondary Owner (Consumer/Provider):** The team managing the downstream or upstream service being integrated with. They must review the integration tests to ensure they accurately represent the API contract and expected behaviors. + +## 2. Test Placement and Infrastructure + +- **Dedicated Integration Repo:** For complex multi-surface features, integration tests should be housed in a centralized `integration-tests` repository or a dedicated directory in the primary consumer's repository. +- **CI/CD Triggers:** + - Cross-repo tests run on nightly builds to avoid slowing down individual service PRs. + - On demand triggers can be executed via GitHub Actions `workflow_dispatch` with specific branch names for PRs that span multiple repos. + +## 3. Coordination Workflow + +1. **RFC / Design Phase:** Any feature spanning multiple repos must include an integration testing plan in its design document. +2. **Contract Agreement:** Service contracts (e.g., OpenAPI, ABI) must be finalized and mockable before cross-repo integration tests are written. +3. **Implementation:** The initiator writes the tests against staging/testnet environments. +4. **Review:** Maintainers from all involved repositories must approve the PR introducing or modifying the integration tests. +5. **Monitoring:** Failures in cross-repo tests should alert the `#integration-alerts` channel, tagging the Primary Owner. + +## 4. Environment Standardization + +Integration tests must be executed against ephemeral environments or dedicated staging instances that closely mirror production, utilizing seeded deterministic data to avoid flakiness. diff --git a/docs/DEFINITION_OF_DONE.md b/docs/DEFINITION_OF_DONE.md new file mode 100644 index 00000000..c149b9a2 --- /dev/null +++ b/docs/DEFINITION_OF_DONE.md @@ -0,0 +1,43 @@ +# Definition of Done (DoD) for Multi-Surface Features + +Features that span across multiple surfaces (Backend, Frontend, Smart Contracts, Infrastructure) require a rigorous Definition of Done to ensure complete, secure, and maintainable delivery. + +Use this checklist before marking a multi-surface feature as "Done". + +## 1. Smart Contracts +- [ ] Code is fully implemented and peer-reviewed by at least two core maintainers. +- [ ] 100% Unit test coverage achieved. +- [ ] Fuzzing and invariant tests implemented and passing. +- [ ] Slither / Static analysis run and all findings addressed or documented. +- [ ] Gas optimization report generated and regressions justified. +- [ ] Contract deployed to testnet and addresses documented. + +## 2. Backend & APIs +- [ ] API endpoints implemented and matching the agreed-upon OpenAPI spec. +- [ ] Database migrations created, tested (up/down), and reviewed. +- [ ] Unit and Integration tests written and passing. +- [ ] Logging (with correlation IDs) and metrics implemented for new flows. +- [ ] Rate limiting and security constraints applied. + +## 3. Frontend +- [ ] UI components implemented matching Figma designs. +- [ ] State management handles loading, success, and error states gracefully. +- [ ] E2E tests (Playwright/Cypress) written for the happy path of the new feature. +- [ ] Feature is responsive across mobile and desktop breakpoints. +- [ ] Web3 integration handles wallet disconnects, network switching, and pending transactions. + +## 4. Documentation +- [ ] User-facing documentation/guides updated. +- [ ] API documentation (Swagger/Postman) updated. +- [ ] Runbooks and incident response procedures updated (if infra/ops changed). +- [ ] Architecture diagrams updated (if new services/components added). + +## 5. Security & Observability +- [ ] Threat modeling considered for the holistic feature. +- [ ] Alerts and dashboards created for new critical metrics (e.g., failure rates). +- [ ] Feature flagged appropriately (if using gradual rollout). + +## 6. Release Management +- [ ] Cross-repo integration tests passing in the staging environment. +- [ ] Deployment checklist and rollback plan created. +- [ ] PR descriptions clearly link to all related PRs across different repositories. diff --git a/docs/ISSUE_TAXONOMY_AND_LABELS.md b/docs/ISSUE_TAXONOMY_AND_LABELS.md new file mode 100644 index 00000000..f812747b --- /dev/null +++ b/docs/ISSUE_TAXONOMY_AND_LABELS.md @@ -0,0 +1,41 @@ +# Repository-Wide Issue Taxonomy and Labeling Standards + +To maintain an organized and triagable backlog, all issues and pull requests must adhere to the following taxonomy and labeling standards. + +## 1. Category Labels (Type) +Every issue must have exactly **one** type label: +* `type: feature` - New functionality or enhancement. +* `type: bug` - Something is broken or not behaving as intended. +* `type: chore` - Maintenance, dependency updates, refactoring, or tooling. +* `type: docs` - Documentation additions or improvements. +* `type: security` - Security vulnerabilities or improvements (Note: sensitive issues should be reported via security policy, not public issues). + +## 2. Surface / Component Labels (Scope) +Indicate which parts of the stack are affected (multiple allowed): +* `scope: contracts` - Smart contracts, Solidity, Foundry. +* `scope: backend` - Node.js, databases, indexers, APIs. +* `scope: frontend` - React, Next.js, UI/UX, Web3 integration. +* `scope: infra` - Deployment, Terraform, CI/CD, GitHub Actions. + +## 3. Severity / Priority Labels +Bugs and critical tasks must have a priority: +* `priority: critical` - Production down, funds at risk. Drop everything. +* `priority: high` - Major feature broken, no workaround. Address in current sprint. +* `priority: medium` - Minor bug, edge case, or has a workaround. +* `priority: low` - Trivial issue, cosmetic bug, nice-to-have. + +## 4. Status / Workflow Labels +Used by PMs and maintainers to track progress: +* `status: needs-triage` - Default for new issues. Needs review. +* `status: ready-for-dev` - Approved, specced out, and ready to be picked up. +* `status: blocked` - Waiting on a dependency, external team, or design. +* `status: in-progress` - Currently being worked on. + +## 5. Workstream / Epic Mapping +For larger initiatives, issues should be tied to a specific workstream: +* `epic: [Name]` - e.g., `epic: v2-vaults`, `epic: compliance-upgrade`. + +## Enforcing Standards +* The triage bot will automatically flag issues missing a `type:` or `scope:` label. +* PRs should inherit the labels of the issue they resolve. +* Avoid creating custom labels without proposing them in the `#engineering` channel first. diff --git a/docs/QUALITY_GATES_MATRIX.md b/docs/QUALITY_GATES_MATRIX.md new file mode 100644 index 00000000..18d21692 --- /dev/null +++ b/docs/QUALITY_GATES_MATRIX.md @@ -0,0 +1,37 @@ +# Quality Gates Matrix by Component Criticality + +This matrix defines the required quality gates, testing standards, and review processes based on the criticality of the component being modified. + +## Criticality Levels + +### Tier 1: Core Smart Contracts & Value Transfer +*Components: Vault Contracts, Token Contracts, Oracle Integrations, Yield Strategies* +- **Unit Test Coverage:** 100% (Line and Branch) +- **Fuzzing/Invariant Testing:** Required (e.g., Echidna, Foundry) +- **Static Analysis:** Slither & Aderyn (0 High/Med findings allowed without documented false positive) +- **Audits:** External audit required for major releases +- **Code Review:** Minimum 2 approvals from Core Contract Maintainers + +### Tier 2: Backend Services & API Layer +*Components: Indexers, Transaction Relayers, Webhooks, Data APIs* +- **Unit Test Coverage:** 90%+ +- **Integration Tests:** Required for all critical paths (deposits, withdrawals) +- **Static Analysis:** SonarQube / ESLint with strict rules +- **Load Testing:** Required for components handling high TPS +- **Code Review:** Minimum 1 approval from Backend Maintainers + +### Tier 3: Frontend & User Interfaces +*Components: Web Dashboard, Admin Panel, Mobile views* +- **Unit Test Coverage:** 80%+ (Focus on utility functions and state management) +- **E2E Testing:** Playwright/Cypress covering critical user journeys (Connect Wallet, Deposit, Withdraw) +- **Accessibility (a11y):** Automated Lighthouse checks passing (Score > 90) +- **Code Review:** Minimum 1 approval from Frontend Maintainers + +### Tier 4: Operational Tooling & Scripts +*Components: Deployment scripts, CI/CD pipelines, internal CLI tools* +- **Review:** 1 approval from DevOps / Infra Maintainer +- **Testing:** Dry-run capabilities required. Bash scripts must pass `shellcheck`. +- **Documentation:** Clear runbooks and inline comments required. + +## Enforcement +These gates are enforced via GitHub Actions branch protection rules. Bypassing these gates requires explicit sign-off from the Tech Lead or Security Lead.