Contributing to Stellar Local

Thank you for your interest in contributing to Stellar Local! This guide will help you get started.

🎯 Quick Start for Contributors

Find an Issue — Browse open issues
Comment — Let us know you're working on it
Fork & Clone — Fork the repo and clone it locally
Branch — Create a feature branch from develop
Code — Make your changes
Test — Ensure all tests pass
PR — Submit a pull request with issue reference

📋 Prerequisites

Before contributing, ensure you have:

Node.js >= 20
Rust (for Soroban contracts)
Docker & Docker Compose
Stellar CLI (for contract deployment)
Git

🚀 Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/Stellar-Local.git
cd Stellar-Local

2. Install Dependencies

# Install all workspace dependencies
npm install

3. Set Up Environment

# Copy environment template
cp .env.example .env

# Update .env with your configuration
# For development, defaults should work fine

4. Start Infrastructure

# Start PostgreSQL, Redis, MongoDB via Docker
docker-compose up -d

5. Build Contracts (Optional)

# If working on Soroban contracts
cd contracts/membership
cargo build --target wasm32-unknown-unknown --release

cd ../marketplace
cargo build --target wasm32-unknown-unknown --release

cd ../community-fund
cargo build --target wasm32-unknown-unknown --release

6. Run Tests

# Run all tests
npm test

# Run specific service tests
cd services/marketplace && npm test

# Run contract tests
cd contracts/membership && cargo test

7. Start Development Server

# Start all services with hot reload
npm run dev

# Or start specific apps/services
cd apps/web && npm run dev           # Frontend at :3000
cd services/api-gateway && npm run dev # API at :4000

🏗️ Project Structure

stellar-local/
├── apps/
│   └── web/                 # Next.js frontend
├── services/
│   ├── api-gateway/         # API Gateway (port 4000)
│   ├── marketplace/         # Marketplace service (port 3001)
│   ├── community-fund/      # Community fund service (port 3002)
│   ├── resource-sharing/    # Resource sharing (port 3003)
│   ├── mutual-aid/          # Mutual aid (port 3004)
│   ├── governance/          # Governance (port 3005)
│   └── reputation/          # Reputation system (port 3006)
├── contracts/
│   ├── membership/          # Soroban membership contract
│   ├── marketplace/         # Soroban marketplace contract
│   └── community-fund/      # Soroban community fund contract
├── packages/
│   ├── shared-types/        # TypeScript types
│   ├── stellar-utils/       # Stellar SDK utilities
│   └── ui-components/       # Shared UI components
├── tests/                   # Integration tests
├── docs/                    # Documentation
└── infrastructure/          # Docker, K8s, Terraform

🔧 Development Workflow

Branching Strategy

main — Production-ready code
develop — Integration branch for features
feature/* — New features
fix/* — Bug fixes
docs/* — Documentation updates

Creating a Feature Branch

# Checkout develop
git checkout develop
git pull origin develop

# Create your feature branch
git checkout -b feature/marketplace-filters

# Make your changes
# ...

# Commit with descriptive messages
git add .
git commit -m "feat(marketplace): add category and price filters"

# Push to your fork
git push origin feature/marketplace-filters

Commit Message Convention

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]
[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style (formatting, no logic change)
refactor: Code restructuring
test: Adding/updating tests
chore: Maintenance tasks

Examples:

feat(marketplace): add listing search
fix(fund): correct balance calculation
docs(readme): update setup instructions
test(membership): add contract unit tests

🧪 Testing

Running Tests

# All tests
npm test

# Frontend tests
cd apps/web && npm test

# Service tests
cd services/marketplace && npm test

# Contract tests
cd contracts/marketplace && cargo test

# Integration tests
npm run test:integration

Writing Tests

Contract Tests (Rust)

#[test]
fn test_create_listing() {
    let env = Env::default();
    let contract_id = env.register_contract(None, MarketplaceContract);
    let client = MarketplaceContractClient::new(&env, &contract_id);
    
    // Test logic
    let listing_id = client.create_listing(&seller, &title, &price);
    assert!(listing_id > 0);
}

Service Tests (TypeScript/Jest)

describe('Marketplace API', () => {
  it('should create a listing', async () => {
    const response = await request(app)
      .post('/listings')
      .send({ title: 'Test Item', price: 100 })
      .expect(201);
    
    expect(response.body.data).toHaveProperty('id');
  });
});

📝 Pull Request Process

Before Submitting

Code follows project style guidelines
All tests pass (npm test)
New features have tests
Documentation is updated
Commit messages follow convention
No merge conflicts with develop

Submitting a PR

Push your branch to your fork
Open a Pull Request against develop (not main)
Reference the issue — e.g., "Closes #42"
Describe your changes — what, why, and how
Request review — tag maintainers if needed

PR Template

## Description
Brief description of what this PR does.

## Related Issue
Closes #42

## Changes
- Added category filter to marketplace
- Updated ListingCard component
- Added filter tests

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manually tested in browser

## Screenshots (if applicable)
[Add screenshots]

Review Process

Maintainers will review your PR within 2-3 days
Address any requested changes
Once approved, a maintainer will merge

🎨 Code Style

TypeScript/JavaScript

Use TypeScript for all new code
Follow ESLint rules
Use Prettier for formatting
Prefer functional patterns over classes where possible

// Good
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// Avoid
export class Calculator {
  calculateTotal(items: Item[]): number {
    let sum = 0;
    for (const item of items) {
      sum += item.price;
    }
    return sum;
  }
}

Rust (Soroban Contracts)

Follow Rust conventions
Use cargo fmt before committing
Run cargo clippy to catch issues
Write tests for all public functions

// Good - clear, concise
pub fn create_listing(env: Env, seller: Address, title: String, price: i128) -> u32 {
    seller.require_auth();
    // Implementation
}

React Components

Use functional components with hooks
Keep components small and focused
Use TypeScript for props
Prefer composition over prop drilling

// Good
interface ListingCardProps {
  listing: Listing;
  onPurchase: (id: string) => void;
}

export function ListingCard({ listing, onPurchase }: ListingCardProps) {
  return (
    <Card>
      <h3>{listing.title}</h3>
      <p>{listing.price} XLM</p>
      <Button onClick={() => onPurchase(listing.id)}>Buy</Button>
    </Card>
  );
}

📚 Documentation

Code Documentation

Contracts — Document public functions with Rust doc comments
Services — Add JSDoc for complex functions
Components — Document props with TypeScript

Writing Docs

Documentation lives in docs/:

docs/
├── architecture.md        # System architecture
├── marketplace.md         # Marketplace module
├── community-fund.md      # Community fund module
├── membership.md          # Membership system
├── getting-started.md     # Setup guide
├── api.md                 # API reference
└── wave-contributions.md  # Wave contribution guide

🐛 Reporting Bugs

Use the Bug Report template:

Include:

Clear description
Steps to reproduce
Expected vs actual behavior
Environment (OS, Node version, etc.)
Screenshots if applicable

💡 Suggesting Features

Use the Feature Request template: