diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..599dd2562 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,73 @@ +# Amana Project Code Ownership +# +# This file defines code ownership and required review rules for critical paths. +# PRs touching these paths require approval from designated code owners. +# +# Syntax: ... +# Owners are GitHub usernames or team references (@org/team-name) + +# ── Smart Contracts ──────────────────────────────────────────────────────────── +# Critical escrow contract logic +contracts/amana_escrow/** @KingFRANKHOOD + +# ── Backend: Core Services ───────────────────────────────────────────────────── +# Authentication and authorization +backend/src/auth/** @KingFRANKHOOD +backend/src/common/guards/** @KingFRANKHOOD +backend/src/common/decorators/** @KingFRANKHOOD + +# Blockchain integration and contract interaction +backend/src/modules/blockchain/** @KingFRANKHOOD +backend/src/modules/transactions/** @KingFRANKHOOD + +# Trade and dispute critical paths +backend/src/modules/claims/** @KingFRANKHOOD +backend/src/modules/disputes/** @KingFRANKHOOD + +# Observability and audit logging +backend/src/common/interceptors/** @KingFRANKHOOD +backend/src/common/filters/** @KingFRANKHOOD + +# Database migrations +backend/src/migrations/** @KingFRANKHOOD + +# ── Backend: Supporting Services ─────────────────────────────────────────────── +# User and admin management +backend/src/modules/user/** @KingFRANKHOOD +backend/src/modules/admin/** @KingFRANKHOOD + +# Savings and governance +backend/src/modules/savings/** @KingFRANKHOOD +backend/src/modules/governance/** @KingFRANKHOOD + +# Notifications and webhooks +backend/src/modules/notifications/** @KingFRANKHOOD +backend/src/modules/webhooks/** @KingFRANKHOOD + +# ── Frontend: Core Components ────────────────────────────────────────────────── +# Dashboard and contract details +frontend/app/components/dashboard/** @KingFRANKHOOD + +# Trade and dispute flows +frontend/app/components/trade/** @KingFRANKHOOD +frontend/app/components/disputes/** @KingFRANKHOOD + +# ── Configuration & Infrastructure ──────────────────────────────────────────── +# Environment and deployment +backend/.env.example @KingFRANKHOOD +backend/Dockerfile @KingFRANKHOOD +backend/docker-compose.yml @KingFRANKHOOD + +# Package dependencies +backend/package.json @KingFRANKHOOD +frontend/package.json @KingFRANKHOOD + +# ── Testing ──────────────────────────────────────────────────────────────────── +# E2E and critical path tests +backend/test/** @KingFRANKHOOD + +# ── Documentation ────────────────────────────────────────────────────────────── +# Governance and contribution guidelines +CONTRIBUTING.md @KingFRANKHOOD +README.md @KingFRANKHOOD +GOALS_PR_DESCRIPTION.md @KingFRANKHOOD diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3397b8b50 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,193 @@ +# Contributing to Amana + +Thank you for your interest in contributing to Amana! This document outlines our contribution guidelines, code ownership policy, and review requirements. + +## Code Ownership & Review Requirements + +We maintain a CODEOWNERS file (`.github/CODEOWNERS`) that defines ownership of critical paths in the codebase. This ensures domain expertise is applied to high-impact changes. + +### Critical Paths Requiring Review + +The following areas require approval from designated code owners before merging: + +#### Smart Contracts +- **Path**: `contracts/amana_escrow/**` +- **Reason**: Core escrow logic affecting fund security and dispute resolution +- **Owner**: @KingFRANKHOOD + +#### Backend: Authentication & Authorization +- **Path**: `backend/src/auth/**`, `backend/src/common/guards/**` +- **Reason**: Security-critical authentication and access control +- **Owner**: @KingFRANKHOOD + +#### Backend: Blockchain Integration +- **Path**: `backend/src/modules/blockchain/**`, `backend/src/modules/transactions/**` +- **Reason**: Contract interaction and transaction integrity +- **Owner**: @KingFRANKHOOD + +#### Backend: Trade & Dispute Critical Paths +- **Path**: `backend/src/modules/claims/**`, `backend/src/modules/disputes/**` +- **Reason**: Core business logic for trade lifecycle and dispute resolution +- **Owner**: @KingFRANKHOOD + +#### Backend: Observability & Audit +- **Path**: `backend/src/common/interceptors/**`, `backend/src/common/filters/**` +- **Reason**: Request tracing, audit logging, and incident debugging +- **Owner**: @KingFRANKHOOD + +#### Database Migrations +- **Path**: `backend/src/migrations/**` +- **Reason**: Schema changes affect all services and data integrity +- **Owner**: @KingFRANKHOOD + +#### Frontend: Dashboard & Contract Details +- **Path**: `frontend/app/components/dashboard/**` +- **Reason**: User-facing contract and trade information +- **Owner**: @KingFRANKHOOD + +### How Code Ownership Works + +1. **Branch Protection**: PRs touching owned paths require approval from the designated code owner +2. **Automatic Checks**: GitHub branch protection rules enforce this requirement +3. **Exceptions**: Code owners can approve exceptions for urgent fixes or emergency patches + +## Contribution Workflow + +### 1. Create a Feature Branch + +```bash +git checkout -b /- +``` + +**Branch naming conventions**: +- `feat/` - New features +- `fix/` - Bug fixes +- `hardening/` - Security or reliability improvements +- `observability/` - Logging, monitoring, tracing +- `governance/` - Policy, documentation, ownership +- `refactor/` - Code improvements without behavior changes + +**Example**: +```bash +git checkout -b hardening/e2e-critical-path-tests +git checkout -b observability/request-correlation-audit-logs +git checkout -b governance/codeowners-required-review +``` + +### 2. Make Your Changes + +- Follow the existing code style and patterns +- Write tests for new functionality +- Update documentation as needed +- Ensure all checks pass locally + +### 3. Commit Your Changes + +Use clear, descriptive commit messages: + +```bash +git commit -m "feat: add E2E tests for critical trade path" +git commit -m "observability: add correlation ID and audit logging" +git commit -m "governance: add CODEOWNERS and review policy" +``` + +### 4. Push and Create a PR + +```bash +git push origin +``` + +Then create a PR on GitHub with: +- Clear title describing the change +- Description of what changed and why +- Reference to related issues (e.g., `Closes #177`) +- Screenshots or test results if applicable + +### 5. Code Review + +- Address feedback from code owners +- Ensure all CI checks pass +- Request re-review after making changes + +## Testing Requirements + +### Unit Tests +- Required for all new services and utilities +- Run: `npm run test` + +### E2E Tests +- Required for critical path changes (trade, dispute, auth) +- Run: `npm run test:e2e` + +### Integration Tests +- Required for blockchain and database interactions +- Run: `npm run test:integration` + +## Commit Message Format + +We follow conventional commits for clear history: + +``` +(): + + + +