Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (89 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

128 lines (89 loc) · 4.86 KB
Raw

Contributing to AgenticPay

Thanks for your interest in contributing to AgenticPay. This guide covers the expectations for code style, commits, pull requests, and testing so contributions are easy to review and merge.

Project Structure

  • frontend/: Next.js web application
  • backend/: Express.js API server
  • contracts/: Soroban smart contracts written in Rust

When possible, keep changes focused to a single area of the codebase. If a change spans multiple areas, call that out clearly in your pull request.

Getting Started

  1. Fork the repository and clone your fork.
  2. Create a branch from main.
  3. Install dependencies in the area you plan to change:
cd backend && npm install
cd frontend && npm install
cd contracts && cargo build
  1. Configure any required environment variables described in README.md.

Code Style Guidelines

General

  • Match the existing structure and naming patterns in the files you touch.
  • Prefer small, focused pull requests over large mixed changes.
  • Do not commit secrets, API keys, or .env files.
  • Add or update tests when behavior changes.

Frontend and Backend

  • Use TypeScript for application code and keep types accurate.
  • Run ESLint before opening a pull request.
  • Avoid introducing any unless there is a clear reason and it is documented in the code.
  • Remove unused imports, variables, and dead code before submitting.
  • Keep components, routes, and services narrowly scoped to one responsibility.

Useful commands:

cd frontend && npm run lint
cd frontend && npm test

cd backend && npm run lint
cd backend && npm test

Smart Contracts

  • Follow existing Rust and Soroban patterns in contracts/src/lib.rs.
  • Keep contract interfaces explicit and deterministic.
  • Build and test contract changes before submitting.

Useful commands:

cd contracts && cargo test
cd contracts && cargo build --target wasm32-unknown-unknown --release

Commit Message Format

Use a short, imperative commit message in this format:

type: brief summary

Recommended commit types:

  • feat: new functionality
  • fix: bug fixes
  • docs: documentation updates
  • refactor: code changes that do not change behavior
  • test: adding or updating tests
  • chore: maintenance work

Examples:

docs: add contributing guide
fix: handle missing invoice validation
feat: add project payment status badge

Try to keep the summary under 72 characters and make each commit represent one logical change.

Pull Request Process

  1. Create a descriptive branch name such as feat/payment-status or docs/contributing-guide.
  2. Make your changes in the smallest reasonable scope.
  3. Run the relevant lint, test, and build commands for the areas you changed.
  4. Push your branch and open a pull request against main.
  5. In the pull request description, include:
    • a short summary of the change
    • linked issue or task reference, if available
    • testing notes describing what you ran
    • screenshots or recordings for UI changes, if applicable
  6. Respond to review feedback with follow-up commits unless a maintainer asks for a squash or rebase.

Testing Requirements

Every contribution should be verified before review.

  • Frontend changes: run npm run lint and npm test in frontend/.
  • Backend changes: run npm run lint and npm test in backend/.
  • Contract changes: run cargo test and cargo build --target wasm32-unknown-unknown --release in contracts/.
  • Cross-cutting changes: run checks for every affected area.
  • If automated coverage is not practical, include clear manual verification steps in the pull request.

Pull requests may be sent back for updates if they do not include appropriate validation for the code they change.

Questions and Support

If you are unsure about an implementation detail, open an issue or start a discussion before investing heavily in a large change. Early alignment helps us review and merge contributions faster.

Frontend Domain Modules

Frontend feature code should live under frontend/src/domains/<domain>/ where the current domains are payments, merchants, wallets, analytics, settings, and developers. Each domain owns components/, hooks/, api/, types/, and pages/ subdirectories plus a barrel export from index.ts.

Use domain aliases for feature imports, for example @payments/hooks or @wallets/api. Shared utilities belong in @shared/*, while design-system primitives belong in @ui/* or the existing components/ui implementation. Direct imports from one domain into another are blocked by the local ESLint boundary rule; move cross-domain code into shared modules instead.

For mechanical migrations, run npm run migrate:domain-imports -- <files...> from frontend/ and then review the diff. New pages can remain in the Next.js app/ tree, but feature-specific logic should be colocated in the owning domain module.