From 842e475e78b965806544d5c5c1d22bb17b9f0edd Mon Sep 17 00:00:00 2001
From: Bojay Liu <189326887+BojayL@users.noreply.github.com>
Date: Fri, 19 Jun 2026 16:23:54 +0800
Subject: [PATCH] Add contributing guide

---
 CONTRIBUTING.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..db5c5a3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing to WaveFlow
+
+WaveFlow is a Stellar-native bounty escrow project. Contributions should stay aligned with the PRD, roadmap, and the merge-to-payout core loop: GitHub merge events are verified by the gateway and converted into Soroban escrow payouts.
+
+## Start with an issue
+
+Pick an open issue before opening a pull request. Prefer issues with a clear scope, acceptance criteria, and a complexity label. If the scope is unclear, ask for clarification on the issue before starting work.
+
+Useful planning references:
+
+- [Product Requirements](docs/PRD.md)
+- [Implementation Roadmap](docs/ROADMAP.md)
+- [Agent guidance](AGENTS.md)
+- [Core loop walkthrough](docs/core-loop.md)
+
+## Issue label workflow
+
+Issue titles use a prefix to identify the main area of the repository:
+
+| Prefix | Area | Typical files |
+|--------|------|---------------|
+| `[contracts]` | Soroban escrow logic | `contracts/waveflow-escrow/` |
+| `[gateway]` | GitHub webhook ingestion and chain attestation | `crates/gateway/` |
+| `[api]` | REST API and admin/read paths | `crates/api/` |
+| `[shared]` | Shared types, config, and errors | `crates/shared/` |
+| `[database]` | Postgres schema and migrations | `migrations/` |
+| `[infra]` | Docker, Render, deployment, and operational config | `Dockerfile.*`, `docker-compose.yml`, `render.yaml`, `scripts/` |
+| `[documentation]` | README, runbooks, and guides | `README.md`, `docs/`, `AGENTS.md` |
+
+Maintainers may also apply program and planning labels:
+
+- `Stellar Wave` or `Drips Wave` marks work that maps to the Wave-style contributor program.
+- `complexity:low`, `complexity:medium`, and `complexity:high` indicate the expected effort and point mapping.
+- Feature labels such as `F1` through `F7` map issues to the PRD feature sections.
+- Launch-gate labels such as `PR-1` through `PR-8` map issues to the production readiness gates in the roadmap.
+
+When an issue is part of the Wave workflow, the maintainer-assigned complexity label is the source of truth for point mapping. Do not add Drips API integration or external payout dependencies to satisfy a Wave-labeled issue.
+
+## Branch and pull request conventions
+
+Use a short, descriptive branch name based on the issue scope:
+
+```text
+<area>-<short-description>
+```
+
+Examples:
+
+- `gateway-verify-delivery-id`
+- `api-program-payouts`
+- `docs-maintainer-runbook`
+
+Pull requests should:
+
+- Link the issue with `Fixes #<issue-number>` when the PR fully resolves it.
+- Keep the change focused on one issue or one feature slice.
+- Include the commands you ran under a validation or testing section.
+- Update documentation when behavior, environment variables, APIs, or operations change.
+- Avoid placeholder production paths, simulated transaction hashes, or hardcoded secrets.
+
+## Stellar-native scope
+
+WaveFlow is an independent Stellar/Soroban implementation of Wave-style mechanics. The PRD's non-goals keep WaveFlow separate from unrelated StellarRoute products, and OQ6 records that the project has no Drips API dependency. The expected flow is:
+
+1. Maintainers lock Stellar assets in Soroban escrow.
+2. Contributors register Stellar wallets.
+3. The gateway verifies GitHub merge events.
+4. The contract pays rewards on-chain using the configured point-to-token ratio.
+
+Keep contributions inside that model unless a maintainer explicitly changes the PRD.
+
+## Local validation
+
+Run the smallest command set that proves your change. Common commands from the repository root are:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --workspace
+```
+
+For focused work, use crate-specific checks such as:
+
+```bash
+cargo test -p waveflow-escrow record_merge_pays_contributor
+cargo test -p waveflow-gateway verify_github_signature
+```
+
+Document any command you could not run and why.
diff --git a/README.md b/README.md
index 351345e..75aff75 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,7 @@ cargo run -p waveflow-api
 
 ## Documentation
 
+- [Contributing Guide](CONTRIBUTING.md)
 - [Product Requirements](docs/PRD.md)
 - [Implementation Roadmap](docs/ROADMAP.md)
 - [Core loop walkthrough](docs/core-loop.md)