diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f549afe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,82 @@ +name: Bug report +description: Report a reproducible problem in the app, API, or contracts. +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. Please include enough detail for a maintainer to reproduce it locally. + - type: textarea + id: summary + attributes: + label: Summary + description: What went wrong? + placeholder: A concise description of the bug. + validations: + required: true + - type: dropdown + id: area + attributes: + label: Affected area + options: + - Frontend + - Backend + - Contracts + - Supabase + - Documentation + - Other + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: List the exact actions, commands, or API calls that trigger the issue. + placeholder: | + 1. Run ... + 2. Open ... + 3. Observe ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + placeholder: What should have happened? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + placeholder: What happened instead? + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Include versions and relevant local setup details. + placeholder: | + OS: + Node: + npm: + Rust: + Stellar CLI: + Supabase CLI: + - type: textarea + id: logs + attributes: + label: Logs or screenshots + description: Paste relevant logs or screenshots. Redact secrets and private keys. + render: shell + - type: checkboxes + id: checks + attributes: + label: Pre-submit checks + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I removed or redacted secrets, private keys, and wallet seed phrases. + required: true diff --git a/.github/ISSUE_TEMPLATE/contract_issue.yml b/.github/ISSUE_TEMPLATE/contract_issue.yml new file mode 100644 index 0000000..4927a79 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/contract_issue.yml @@ -0,0 +1,68 @@ +name: Contract issue +description: Report or propose a change that affects Soroban contract behavior. +title: "[Contract]: " +labels: ["contract"] +body: + - type: markdown + attributes: + value: | + Contract issues can affect escrowed funds and security guarantees. Include precise function and invariant details. + - type: textarea + id: summary + attributes: + label: Summary + placeholder: Briefly describe the contract concern. + validations: + required: true + - type: input + id: contract + attributes: + label: Contract or module + placeholder: contracts/secureflow/src/... + validations: + required: true + - type: textarea + id: functions + attributes: + label: Affected function(s) + description: Name the public entrypoints, helpers, or storage paths involved. + placeholder: | + - create_contract + - release_milestone + validations: + required: true + - type: textarea + id: security + attributes: + label: Security implications + description: Could this affect funds, authorization, state integrity, replay resistance, or privacy? + placeholder: Describe the worst credible impact and affected actors. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected invariant or behavior + placeholder: What property should always hold? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction or test idea + placeholder: Provide a failing test case, transaction sequence, or command. + - type: textarea + id: validation + attributes: + label: Suggested validation + placeholder: | + cargo fmt --all --check + cargo clippy --workspace --all-targets -- -D warnings + cargo test --workspace + - type: checkboxes + id: disclosure + attributes: + label: Disclosure + options: + - label: This issue does not include secrets, private keys, wallet seed phrases, or exploitable private data. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..c395b83 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,66 @@ +name: Feature request +description: Suggest a product, developer experience, or platform improvement. +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Use this template for scoped enhancements. Larger architectural proposals should include rollout and testing notes. + - type: textarea + id: problem + attributes: + label: Problem + description: What user or developer problem does this solve? + placeholder: Describe the pain point or missing workflow. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: What should change? + placeholder: Describe the desired behavior or API. + validations: + required: true + - type: dropdown + id: area + attributes: + label: Affected area + options: + - Frontend + - Backend + - Contracts + - Supabase + - Documentation + - Developer experience + - Other + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + placeholder: Note any simpler alternatives or tradeoffs. + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: How will maintainers know this is done? + placeholder: | + - [ ] ... + - [ ] ... + validations: + required: true + - type: textarea + id: validation + attributes: + label: Suggested validation + placeholder: Commands, tests, or manual checks that should pass. + - type: checkboxes + id: checks + attributes: + label: Pre-submit checks + options: + - label: I searched existing issues and did not find a duplicate. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..22326cb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ +## Summary + +- + +## Why + +Explain the reason for the change and link the issue. + +Closes # + +## Test evidence + +List the exact commands you ran and their results. + +```bash +# example +npm run lint +``` + +## Risk and rollout + +- Risk level: +- Rollout notes: +- Follow-up work: + +## Checklist + +- [ ] I kept this PR focused on one issue or feature. +- [ ] I added or updated tests for behavior changes, or explained why not. +- [ ] I updated docs for setup, route, migration, contract, or environment changes. +- [ ] I ran the smallest relevant validation commands and included them above. +- [ ] I checked that no secrets, private keys, wallet seed phrases, or `.env` files are committed. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e015aa..36b2e08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,200 @@ -# Contributing +# Contributing to Secureflow -This is a guide to contributing to `scaffold-stellar-frontend` itself. Feel free to delete or modify it for your own project. +Thank you for helping improve Secureflow. This guide is intended to get a new contributor from a clean machine to a focused pull request without needing private project context. + +## Prerequisites + +Install the tools for the layer you plan to change. + +### Frontend + +- Node.js 20 or newer +- npm 10 or newer + +```bash +node --version +npm --version +``` + +### Backend + +- Node.js 20 or newer +- npm 10 or newer +- Supabase CLI for local database work + +```bash +npm install -g supabase +supabase --version +``` + +### Contracts + +- Rust toolchain +- Stellar CLI with Soroban support + +```bash +rustup default stable +cargo --version +stellar --version +``` + +If the Stellar CLI is missing, run the repository helper: + +```bash +./install-soroban.sh +``` + +## Local setup + +Clone the repository and install root dependencies: + +```bash +git clone https://github.com/Secureflow-protocol/secureflow.git +cd secureflow +npm install +``` + +Do not commit secrets, private keys, wallet seed phrases, Supabase service-role credentials, or local `.env` files. + +## Environment files + +Create only the environment files required by the layer you are changing. Prefer local development keys and public testnet values. + +Common locations: + +- Root frontend: `.env.local` +- Backend API: `backend/.env` +- Supabase local stack: `supabase/.env`, if needed by your local CLI setup +- Contract/testnet scripts: root `.env` values consumed by `deploy.sh` or contract helper scripts + +## Frontend workflow + +Install dependencies at the repository root, then start Vite: + +```bash +npm install +npm run dev +``` + +Build and lint before opening a PR that changes frontend code: + +```bash +npm run lint +npm run build +``` + +When working with generated contract clients, install and build the generated workspace: + +```bash +npm run install:contracts +``` + +## Backend workflow + +Install backend dependencies and start the API: + +```bash +cd backend +npm install +npm run dev +``` + +Build before opening a PR that changes backend TypeScript: + +```bash +npm run build +``` + +Keep request validation, route behavior, and Supabase table fields aligned with `supabase/migrations/` and `supabase/seed.sql`. + +## Supabase workflow + +The repository includes migrations and local seed data. + +```bash +supabase start +supabase db reset +``` + +`supabase db reset` recreates the local database, applies migrations, and loads `supabase/seed.sql`. The seed data includes sample messages and notifications so local inbox and notification routes have records to return. + +Stop the local stack when you are done: + +```bash +supabase stop +``` + +## Contract workflow + +Build and test the Soroban contracts from the repository root: + +```bash +cargo fmt --all --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +``` + +Use `cargo fmt --all` before committing contract changes. For security-sensitive changes, describe the affected contract functions and expected invariants in the PR. + +## Code style + +- TypeScript and React code should pass `npm run lint`. +- Format frontend/backend files with Prettier through the existing npm scripts or editor integration. +- Rust code should pass `cargo fmt --all --check` and `cargo clippy`. +- Keep changes focused on one issue. Avoid unrelated formatting churn. +- Prefer small, named helpers over copying route, validation, or contract logic across files. + +## Tests + +Run the smallest relevant validation command for your change and include the exact command in the PR description. + +Useful commands: + +```bash +# Frontend +npm run lint +npm run build + +# Backend +cd backend +npm run build + +# Contracts +cargo fmt --all --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +``` + +If you cannot run a relevant command, explain why in the PR and describe the manual review you performed. + +## Conventional commits + +Use concise conventional commit messages: + +```text +type(scope): summary +``` + +Examples: + +- `docs(contributing): expand local setup guide` +- `fix(backend): validate milestone payloads` +- `test(contract): cover escrow cancellation path` + +Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`. + +## Pull request checklist + +Before opening a PR: + +- Link the issue with `Closes #123` or `Fixes #123`. +- Explain why the change is needed, not only what changed. +- Add or update tests for behavior changes when practical. +- Include test evidence with exact commands and results. +- Update docs when setup, migrations, routes, contracts, or environment variables change. +- Confirm lint/build/format checks pass for the changed layer, or explain why they were not run. +- Confirm no secrets, private keys, wallet seed phrases, or local `.env` files were committed. + +## Review expectations + +Maintainers may ask for smaller changes, more tests, or clearer setup instructions. Keep follow-up commits focused and reply with the validation command you reran.