From 3f237eff1f5de8eec123e77c48cbeaed12df42b6 Mon Sep 17 00:00:00 2001 From: huazhuang80-star <295584745+huazhuang80-star@users.noreply.github.com> Date: Mon, 22 Jun 2026 10:09:50 +0800 Subject: [PATCH] docs: expand contributing guide and templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 69 ++++++++++ .github/ISSUE_TEMPLATE/contract_issue.yml | 58 ++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 48 +++++++ .github/pull_request_template.md | 31 +++++ CONTRIBUTING.md | 152 ++++++++++++++++++++- 5 files changed, 357 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/contract_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..caff782 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,69 @@ +name: Bug report +description: Report a reproducible SecureFlow bug. +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve SecureFlow. Do not include private keys, seed phrases, access tokens, or customer data. + - type: textarea + id: summary + attributes: + label: Summary + description: What happened, and what did you expect instead? + placeholder: The escrow creation flow fails when... + validations: + required: true + - type: textarea + id: steps + attributes: + label: Reproduction steps + description: List exact steps so a maintainer can reproduce the issue. + placeholder: | + 1. Run ... + 2. Open ... + 3. Click ... + validations: + required: true + - type: dropdown + id: area + attributes: + label: Affected area + options: + - Frontend + - Backend + - Soroban contract + - Generated contract client + - Documentation + - CI/tooling + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Include OS, Node, Rust, Stellar CLI, browser, and network where relevant. + placeholder: | + OS: + Node: + Rust: + Stellar CLI: + Network: + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs or screenshots + description: Paste sanitized logs or attach screenshots if useful. + render: shell + - type: checkboxes + id: checklist + attributes: + label: Safety checklist + options: + - label: I removed secrets, private keys, seed phrases, and tokens from this report. + required: true + - label: I searched existing issues before opening this one. + required: true diff --git a/.github/ISSUE_TEMPLATE/contract_issue.yml b/.github/ISSUE_TEMPLATE/contract_issue.yml new file mode 100644 index 0000000..3f50c0d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/contract_issue.yml @@ -0,0 +1,58 @@ +name: Contract issue +description: Report or propose a Soroban contract change. +title: "[Contract]: " +labels: ["contract"] +body: + - type: markdown + attributes: + value: | + Contract issues can affect funds and authorization. Do not publish exploit details for a live vulnerability; open a minimal report and ask maintainers for a private disclosure path. + - type: input + id: function + attributes: + label: Affected function or module + placeholder: escrow_management::create_escrow + validations: + required: true + - type: textarea + id: behavior + attributes: + label: Current behavior + description: What does the contract do today? + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should the contract do instead? + validations: + required: true + - type: dropdown + id: security + attributes: + label: Security implications + options: + - None known + - Authorization or access control + - Funds can be locked + - Funds can be misdirected + - Accounting or invariant drift + - Denial of service + - Unsure + validations: + required: true + - type: textarea + id: tests + attributes: + label: Suggested tests + description: What unit, integration, or invariant tests should cover this? + placeholder: | + - ... + - type: checkboxes + id: checklist + attributes: + label: Safety checklist + options: + - label: I did not include private keys, seed phrases, or live exploit instructions. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..b9c0277 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,48 @@ +name: Feature request +description: Propose a product, protocol, or developer-experience improvement. +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What user, contributor, or protocol problem would this solve? + placeholder: Freelancers need a way to... + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the smallest useful version of the feature. + validations: + required: true + - type: dropdown + id: area + attributes: + label: Primary area + options: + - Frontend + - Backend + - Soroban contract + - Generated contract client + - Documentation + - CI/tooling + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Mention any simpler or safer approaches. + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: What must be true before this can be considered done? + placeholder: | + - [ ] ... + - [ ] ... + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..deb6f5d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,31 @@ +## Summary + +- + +## Why + +- + +## Test evidence + +- [ ] Frontend checks run (`npm run lint`, `npm run build`, or relevant subset) +- [ ] Backend checks run from `backend/` +- [ ] Contract checks run (`cargo fmt`, `cargo clippy`, `cargo test`, or relevant subset) +- [ ] Documentation-only change, no runtime checks needed + +Commands and results: + +```text + +``` + +## Risk and security + +- [ ] No private keys, seed phrases, API tokens, or customer data are included +- [ ] Contract changes describe authorization and fund-flow impact +- [ ] UI/API changes include screenshots, logs, or request/response examples where useful +- [ ] Breaking changes are called out + +## Reviewer notes + +- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e015aa..d3992ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,153 @@ # Contributing -This is a guide to contributing to `scaffold-stellar-frontend` itself. Feel free to delete or modify it for your own project. +Thanks for helping make SecureFlow a stronger Stellar escrow protocol. This +guide is intended to get a new contributor from a fresh clone to a focused pull +request without needing private project context. + +## Prerequisites + +Install the tools used by the frontend, backend, and Soroban contract +workspaces: + +```bash +# Node.js 22+ +node --version +npm --version + +# Rust and the Soroban WASM target +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +rustup target add wasm32v1-none + +# Stellar Scaffold CLI +cargo install stellar-scaffold-cli + +# Optional local Stellar network +docker --version +``` + +Never commit private keys, seed phrases, API tokens, `.env` files, customer +data, or production contract credentials. + +## Repository layout + +| Path | Purpose | +| --- | --- | +| `contracts/secureflow/` | Soroban smart contract modules for escrow, marketplace, refunds, ratings, and admin flows. | +| `src/` | React/Vite frontend and generated contract client integration. | +| `backend/` | Express API for gasless relay, uploads, AI helpers, messages, and notifications. | +| `src/contracts/generated/` | Scaffold-generated TypeScript contract bindings. Regenerate instead of editing by hand when the contract changes. | + +## Local setup + +```bash +git clone https://github.com/Secureflow-protocol/secureflow.git +cd secureflow + +# Frontend dependencies +npm install + +# Backend dependencies +cd backend +npm install +cd .. +``` + +Create local environment files from the examples described in `README.md`. +Keep real credentials local only. + +To run a local Stellar network for contract work: + +```bash +docker run --rm -p 8000:8000 stellar/quickstart:testing --local +``` + +Build the contract and generated client after contract changes: + +```bash +stellar scaffold build --build-clients +``` + +## Running the app + +Frontend: + +```bash +npm run dev +``` + +Backend: + +```bash +cd backend +npm run dev +``` + +## Tests and quality checks + +Run the smallest relevant set before opening a PR, then mention exactly what +passed in the PR description. + +Frontend: + +```bash +npm run lint +npm run build +``` + +Backend: + +```bash +cd backend +npm run build +``` + +Contracts: + +```bash +cargo fmt --check +cargo clippy --all-targets -- -D warnings +cargo test +``` + +If a command cannot run because a tool is unavailable, say so in the PR and +explain what you checked instead. + +## Code style + +- Keep PRs small and focused on one issue. +- Prefer clear names and straightforward control flow over clever abstractions. +- Use ESLint and Prettier for TypeScript changes. +- Use `cargo fmt` and `cargo clippy` for Rust changes. +- Add tests or test notes for behavior changes. +- Explain why the change is needed, not only what files changed. + +## Commit format + +Use conventional commits: + +```text +feat: add escrow dispute timeline +fix: reject unauthorized milestone approval +docs: expand contributor setup guide +test: cover refund deadline boundary +chore: update generated contract client +``` + +## Pull request checklist + +Before requesting review: + +- [ ] The PR links the issue it addresses. +- [ ] The change is scoped to one concern. +- [ ] Relevant tests, lint, build, or formatting checks were run. +- [ ] Documentation was updated when behavior or setup changed. +- [ ] Security-sensitive contract or backend changes describe authorization, + fund-flow, and failure-mode impact. +- [ ] No secrets, keys, seed phrases, tokens, or private user data are included. + +## Issue reports + +Use the GitHub issue templates when opening bugs, feature requests, or contract +issues. For security-sensitive contract behavior, avoid posting live exploit +details publicly; provide a minimal report and ask maintainers for a private +disclosure path.