diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8262acb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing to ChainForge + +Thank you for helping improve ChainForge. This guide describes the repository-wide contribution path. Service-specific setup and coding conventions live in each `app/` subdirectory. + +## Contribution ladder + +| Role | Typical scope | Responsibilities | How to progress | +|---|---|---|---| +| Contributor | Issues, documentation, tests, small fixes | Follow the PR checklist, keep changes focused, and respond to review feedback | Land several focused PRs that follow project conventions | +| Reviewer | Code review and triage in familiar areas | Review PRs for correctness, tests, security, and maintainability | Provide consistent, constructive reviews and help newer contributors | +| Maintainer | Ownership of one or more services or workflows | Triage issues, approve PRs, guide roadmap work, and keep CI healthy | Demonstrate sustained ownership and project judgment | +| Core Maintainer | Cross-project governance and releases | Resolve cross-service decisions, coordinate releases, and steward project direction | Be nominated by existing core maintainers after sustained maintainer work | + +Role changes are based on demonstrated trust, project knowledge, and respectful collaboration rather than a fixed number of commits. + +## Development workflow + +1. Open or comment on an issue before starting larger changes. +2. Fork the repository and create a focused branch. +3. Follow the setup instructions for the affected service. +4. Add or update tests when behavior changes. +5. Update documentation when APIs, configuration, workflows, or user-facing behavior changes. +6. Open a pull request that links the issue and summarizes testing. + +## Pull request checklist + +- The PR addresses one clear concern. +- Tests, linting, or a documented manual check were run. +- New configuration is documented with safe example values. +- Secrets, keys, wallets, seed phrases, and private data are not committed. +- Security-sensitive or on-chain changes include enough context for careful review. + +## Review expectations + +Reviewers should focus on correctness, security, reliability, and maintainability. Prefer clear, actionable feedback. Contributors should respond to requested changes or explain tradeoffs when a suggestion cannot be applied. + +## Getting help + +Use the issue thread or pull request discussion for project-specific questions. For service setup, start with the README in the affected `app/` directory. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..f86bd7d --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,31 @@ +# Governance + +ChainForge uses lightweight, maintainer-led governance. The goal is to keep decisions transparent while allowing small, well-scoped contributions to move quickly. + +## Decision model + +| Decision type | Owner | Process | +|---|---|---| +| Small fixes and documentation | Area maintainer or reviewer | Normal pull request review | +| Service-level feature work | Area maintainer | Issue discussion followed by pull request review | +| Cross-service architecture | Maintainers for affected services | Design discussion in an issue before implementation | +| Security-sensitive changes | Core maintainers and affected area maintainers | Private disclosure when needed, followed by coordinated fix and public notes | +| Releases and roadmap priorities | Core maintainers | Consensus after reviewing project impact and maintenance cost | + +Consensus means maintainers have had a fair chance to review and no unresolved blocking concerns remain. If consensus is not reached, core maintainers make the final call and document the reasoning. + +## Maintainer responsibilities + +- Keep issue and pull request triage moving. +- Ask for tests or documentation when a change affects behavior or operations. +- Be explicit about security, privacy, and on-chain risk. +- Help contributors understand project conventions. +- Avoid merging changes that introduce secrets or unsafe defaults. + +## Contributor recognition + +Maintainers may nominate contributors for reviewer or maintainer roles after repeated, high-quality contributions. Nominations should consider code quality, review quality, communication, and reliability across more than one contribution. + +## Conflict resolution + +When discussion stalls, maintainers should restate the open decision, list the tradeoffs, and invite final comments. Core maintainers can then decide, with a short note explaining why the chosen direction best serves ChainForge users and maintainers. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..70d8be3 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,33 @@ +# Maintainers + +This file defines the maintainer role model for ChainForge. The current maintainer roster should be updated by project owners as roles are assigned. + +## Maintainer areas + +| Area | Scope | Maintainers | +|---|---|---| +| Smart contracts | Soroban contracts, on-chain tests, deployment scripts | TBD | +| Backend | NestJS API, Prisma, workers, integrations | TBD | +| Frontend | Next.js admin dashboard and shared UI | TBD | +| Mobile | Expo app, offline workflows, wallet integrations | TBD | +| AI service | FastAPI service, OCR, anonymization, fraud detection | TBD | +| Operations | CI, deployment, observability, documentation | TBD | + +## Reviewer expectations + +Reviewers help maintainers by checking focused pull requests in areas they understand. Reviews should verify that changes are scoped, tested, documented when needed, and aligned with project conventions. + +## Maintainer expectations + +Maintainers own project health for their area. They triage issues, review pull requests, guide new contributors, and coordinate with other maintainers when a change crosses service boundaries. + +## Becoming a maintainer + +A contributor can be nominated after sustained, constructive participation. Existing maintainers should consider: + +- Quality and consistency of merged contributions. +- Helpfulness and accuracy in reviews. +- Judgment around security, privacy, and operational risk. +- Willingness to support other contributors after code is merged. + +Role changes should be noted in this file so contributors know who can help with each area. diff --git a/README.md b/README.md index 34fd9dd..9533f43 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,8 @@ We welcome contributions that make humanitarian aid delivery more transparent an For component-specific contribution guidelines, refer to the README in each `app/` subdirectory. +See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository-wide contribution ladder and pull request workflow. Governance and maintainer responsibilities are documented in [GOVERNANCE.md](GOVERNANCE.md) and [MAINTAINERS.md](MAINTAINERS.md). + --- ## License