Skip to content

Add a CONTRIBUTING.md guide with local dev setup, code style, and PR checklist #34

Description

@MJ-RWA

Complexity: Medium — 150 pts

Summary

StellarFlow has a README but no CONTRIBUTING.md. New contributors — especially those coming in through Drip Wave — have no guidance on how to set up the dev environment, what the code conventions are, how to run tests, or what a PR needs to include to get merged. This issue creates a thorough CONTRIBUTING.md that makes the contributor experience smooth and reduces back-and-forth in PR reviews.

Files to Create/Modify

  • Create: CONTRIBUTING.md at the repo root
  • Modify: README.md — add a "Contributing" badge and link to CONTRIBUTING.md near the top

Required sections (in order)

  1. Prerequisites — table of Node.js ≥18, npm ≥9, Git, Freighter (testnet), Bruno (optional)
  2. Local Development Setup — fork/clone, npm install, npm run dev, fund a testnet account via Friendbot, add a USDC trustline for swap testing
  3. Project Structure — annotated file tree with a "rule of thumb" for where new code goes (lib/stellar.ts for blockchain ops, pages/ for routes, components/ for shared UI, hooks/ for data fetching)
  4. Code Style & Conventions — TypeScript-only, named vs default exports, Tailwind-only styling with the existing design tokens, try/catch + toast.error() for all async errors, no hardcoded addresses, import type for type-only imports, 28-byte memo enforcement
  5. Working with the Stellar SDK — the standard "load account → build tx → return XDR" pattern, why submitTx from stellar.ts must be used instead of server.submitTransaction, and a Horizon error code reference table (op_underfunded, op_no_trust, op_no_destination, tx_bad_seq)
  6. Testing Your Changes — manual checklist (build passes, lint passes, tested in Chrome+Freighter testnet, tested at 390px mobile width, no console errors) plus feature-specific test notes for Send, Swap, Recurring, and Request/Pay
  7. Submitting a PR — branch naming conventions (feat/, fix/, docs/, refactor/), Conventional Commits format, and a full PR description template with Closes #XX
  8. PR Checklist — at least 12 items covering issue linking, build/lint, screen recording, hardcoded addresses, error states, mobile responsiveness, Tailwind tokens, console.log cleanup, route/nav registration, hook cleanup, and submitTx usage
  9. Getting Help — GitHub Discussions, GitHub Issues, Stellar Developer Discord, Stellar docs, Horizon API reference

Acceptance Criteria

  • CONTRIBUTING.md exists at the repo root
  • All 9 sections present: Prerequisites, Setup, Structure, Code Style, SDK guide, Testing, PR submission, Checklist, Help
  • Local dev setup steps work exactly as written (tested on a fresh clone)
  • Code style rules match the actual patterns in the existing codebase
  • Horizon error code table is accurate
  • Branch naming and commit message conventions are clearly defined
  • PR description template is included and uses GitHub's issue-linking syntax (Closes #XX)
  • PR checklist has at least 12 items covering build, lint, screen recording, mobile, and Stellar-specific rules
  • README.md updated to link to CONTRIBUTING.md
  • No broken links in the document

Screen Recording Requirements

  1. A fresh clone of the repo — run npm install and npm run dev exactly as the guide describes
  2. The app opens at http://localhost:5173 without errors
  3. Scroll through CONTRIBUTING.md rendered on GitHub to show all sections are present and formatted
  4. Show the PR template by opening a draft PR on GitHub — confirm the template auto-fills

Metadata

Metadata

Assignees

No one assigned

    Labels

    MediumComplexity: Medium — 150 ptsStellar wavedocumentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions