Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
242 lines (160 loc) · 6.63 KB

CONTRIBUTING.md

File metadata and controls

242 lines (160 loc) · 6.63 KB
Raw

Contributing to Predinex Stellar

Welcome, and thank you for your interest in contributing! This guide covers everything you need to go from a clean checkout to an open pull request: local setup, running checks, documentation standards, and the issue workflow.

Table of Contents

  1. Prerequisites
  2. Local Setup
  3. Running Web Checks
  4. Running Contract Checks
  5. Documentation Standards
  6. Issue and PR Workflow
  7. CI Expectations

1. Prerequisites

Tool Minimum version Notes
Node.js 18 22 is used in CI
npm 8 Do not use pnpm or yarn — it creates lockfile conflicts
Rust + Cargo stable (1.74+) Install via rustup.rs
wasm32-unknown-unknown — rustup target add wasm32-unknown-unknown
Stellar CLI 21+ Installation guide
Freighter wallet latest freighter.app — browser extension for UI testing

Run the bootstrap script to verify everything is installed:

./scripts/bootstrap.sh

2. Local Setup

Clone and install

git clone <repository-url>
cd predinex-stellar

# Install web dependencies
cd web
npm install
cd ..

Environment variables

Create web/.env.local with:

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_NETWORK=testnet
NEXT_PUBLIC_SOROBAN_CONTRACT_ID=<testnet-contract-C-strkey>

The contract address for the shared testnet deployment is in web/.env.example. For a local deployment, follow the Local End-to-End Runbook.

Start the development server

cd web
npm run dev

Open http://localhost:3000.

3. Running Web Checks

All three checks must pass before opening a PR. Run them from the web/ directory:

# Lint
npm run lint

# Unit tests (single run, matches CI)
npm test -- --run

# Production build
npm run build

Test suite

Tests live in web/tests/ and use Vitest with React Testing Library.

Directory What it covers
tests/components/ React component behaviour
tests/routes/ Route-level smoke tests — verifies every top-level App Router page mounts without crashing
tests/lib/ API client and utility functions
tests/helpers/ Shared render helpers (renderWithProviders)
tests/integration/ Cross-cutting integration scenarios

Run a single file during development:

npm test -- --run tests/routes/smoke.test.tsx

Run in watch mode while iterating:

npm test -- --watch

Run with coverage:

npm run test:coverage

When adding a new top-level route, add a smoke test entry to tests/routes/smoke.test.tsx so CI catches broken imports or missing providers at the route level.

4. Running Contract Checks

Run these from contracts/predinex/:

# Format check
cargo fmt --check

# Lint
cargo clippy -- -D warnings

# Unit tests
cargo test

To build the WASM artifact:

stellar contract build

The compiled output lands at contracts/predinex/target/wasm32-unknown-unknown/release/predinex.wasm.

For a full local deploy-to-testnet walkthrough, see the Local End-to-End Runbook.

5. Documentation Standards

Code comments

Only add a comment when the why is non-obvious — a hidden constraint, a subtle invariant, or a workaround for a specific bug. Do not comment on what the code does; well-named identifiers already do that.

JSDoc

Add JSDoc to exported utility functions and complex hooks. One short summary line is enough; avoid multi-paragraph blocks.

Architecture docs

Significant architectural decisions (new caching strategies, contract interface changes, new hooks) belong in web/docs/. Reference them from web/DEVELOPMENT.md or web/FRONTEND.md as appropriate.

Contract interface changes

Any change that touches the contract interface must follow the process in docs/CONTRACT_VERSIONING.md. Breaking changes require an explicit major version bump and a migration note before the PR can be merged.

6. Issue and PR Workflow

Picking up an issue

  1. Comment on the issue to let others know you are working on it.
  2. Fork the repository and clone your fork.
  3. Create a branch from main using the convention below.

Branch naming

<type>/<short-description>

Examples:

  • feat/route-smoke-tests
  • fix/market-pagination-reset
  • docs/contributing-guide
  • refactor/wallet-adapter-cleanup

Commit messages

Write imperative-mood subject lines under 72 characters. Put context in the body when needed.

feat: add smoke tests for all top-level App Router routes

Covers home, markets, create, dashboard, disputes, rewards,
activity, and incentives. Uses a shared provider harness so
route-level provider failures are caught independently of the
component suite.

Pull request checklist

Before marking a PR ready for review:

  • npm run lint passes
  • npm test -- --run passes (no new failures)
  • npm run build succeeds
  • Contract checks pass if contract files were touched (cargo fmt --check, cargo clippy, cargo test)
  • PR description references the issue number(s) with Closes #<number>
  • New top-level routes include a smoke test entry in tests/routes/smoke.test.tsx
  • New architectural decisions are documented in web/docs/

PR description template

The repository provides a pull request template at .github/PULL_REQUEST_TEMPLATE.md. Fill it in completely — incomplete descriptions slow down review.

7. CI Expectations

The CI workflow (.github/workflows/ci.yml) runs on every push and pull request to main. It includes:

Job Steps
Web Checks npm ci → npm run lint → npm test -- --run → npm run build
Bundle size budget Checked on PRs; fails if JS exceeds 350 KB, CSS exceeds 80 KB, or total static exceeds 500 KB
Contract Checks cargo fmt --check → cargo clippy -- -D warnings → cargo test

Run all of these locally before pushing to avoid CI failures blocking your PR.

For deeper context on the project architecture, see: