Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (129 loc) · 5.31 KB

CONTRIBUTING.md

File metadata and controls

172 lines (129 loc) · 5.31 KB
Raw

Contributing

Thank you for your interest in contributing to Stellar Goal Vault!

Quick start

  1. Fork the repository on GitHub.
  2. Clone your fork: git clone https://github.com/YOUR_USERNAME/stellar-goal-vault.git
  3. Install dependencies: npm run install:all
  4. Create a branch: git checkout -b feature/my-feature
  5. Make your changes and test them.
  6. Commit using conventional commits (e.g., feat: add new endpoint).
  7. Push and open a Pull Request against the main branch.

Before you start

Backend Development

Prerequisites

  • Node.js 18+ (check with node --version)
  • npm 9+ (comes with Node.js)

Setup

  1. Navigate to the backend directory:

    cd backend

  2. Install dependencies:

    npm install

  3. Copy the environment file:

    cp .env.example .env

  4. Configure environment variables in .env:

    • DB_PATH: Path to SQLite database file (default: ../../data/campaigns.db)
    • NODE_ENV: Set to development for local development
    • PORT: Server port (default: 3000)
    • CORS_ALLOWED_ORIGINS: Comma-separated list of allowed origins
    • CONTRACT_ID: Stellar contract ID (required for pledge operations)
    • SOROBAN_RPC_URL: URL to Soroban RPC endpoint
    • NETWORK_PASSPHRASE: Stellar network (default: Test SDF Network ; September 2015 for testnet)

Running the Backend

  • Development mode (with auto-reload):

    npm run dev

    Server listens on http://localhost:3000 by default.

  • Production mode (build and run):

    npm run build
npm start

  • Watch mode (for editing and testing):

    npm run dev

Testing

  • Run all tests once:

    npm test

  • Run tests in watch mode (re-run on file changes):

    npm run test:watch

  • Run with coverage:

    npm test -- --coverage

Database

  • Seeding: The application automatically initializes the SQLite database with the schema on first run. To seed deterministic test campaigns:

    npm test -- tests/services/seedDeterministic.test.ts

  • Viewing the database:

  • Resetting the database (for testing):

    • Delete the database file: rm ../../data/campaigns.db
    • Next run will recreate it with the schema

Troubleshooting

See the Troubleshooting Guide for a comprehensive list of common issues.

"SQLITE_CANTOPEN" or database file not found

  • Ensure the directory specified in DB_PATH exists
  • Check file permissions on the database directory
  • If the directory doesn't exist, create it: mkdir -p data

Tests fail with "database is locked"

  • This indicates concurrent access issues. Ensure only one test process is running.
  • Try clearing the test database: rm test-temp-*.db*
  • Run tests serially: npm test -- --no-coverage

"Cannot find module" errors

  • Run npm install in the backend directory
  • Clear node_modules and reinstall: rm -rf node_modules && npm install

Port already in use

  • Change the PORT in .env to an available port (e.g., 3001)
  • Or kill the process on the current port

Environment variable not picked up

  • Ensure .env file is in the backend directory
  • Restart the development server after editing .env
  • Check for syntax errors in .env (no spaces around =)

Testing

  • Backend: cd backend && npm test
  • Contract: cd contracts && cargo test
  • E2E: npm run test:e2e

Code style

  • TypeScript: ESLint + Prettier (pre-commit via Husky + lint-staged)
  • Rust: cargo fmt

Adding new open issues

The GET /api/open-issues endpoint serves a statically seeded list of contribution ideas that are displayed in the frontend Contribution Backlog panel.

To add a new issue:

  1. Open backend/src/services/openIssues.ts.
  2. Append a new entry to the seededIssues array: 
    {
  id: 'SGV-4',                                    // continue the SGV-N sequence
  title: 'Short, descriptive title',
  labels: ['frontend', 'good first issue'],
  summary: 'One or two sentences describing the work.',
  complexity: 'Trivial',                          // Trivial | Medium | High
  points: 100,                                    // 100 | 150 | 200
}
  3. Match points to complexity: Trivial → 100, Medium → 150, High → 200.
  4. No migration or server restart is needed — the endpoint reads the array directly.

Full endpoint documentation (example response, field table, complexity/points enum): docs/API.md — GET /api/open-issues

Questions?

Check the FAQ.md before opening an issue. If your question isn't covered there, feel free to open a GitHub Discussion.