Skip to content

NEW_CONTRIBUTOR_GUIDE.md

Latest commit

 

History

History
404 lines (288 loc) · 8.95 KB

NEW_CONTRIBUTOR_GUIDE.md

File metadata and controls

404 lines (288 loc) · 8.95 KB
Raw

New Contributor Guide

Welcome to CarbonLedger! This guide will help you go from zero to running tests locally in under 30 minutes.

📚 Documentation Overview

We've created comprehensive guides to help you get started:

🚀 Quick Start (15-25 minutes)

Quick Start Guide - Fastest path to running tests

  • 5-step setup process
  • Automated verification scripts
  • Time breakdown for each step
  • Success criteria checklist

📖 Complete Setup Guide

Contributing Guide - Detailed setup with troubleshooting

  • Exact version requirements for all tools
  • Platform-specific instructions (macOS, Linux, Windows)
  • Common setup errors with fixes
  • Code style guidelines
  • Development workflow

✅ Verification Checklist

Setup Checklist - Step-by-step verification

  • 30+ checkpoints to verify setup
  • Commands to test each component
  • Automated verification scripts
  • Troubleshooting references

🔧 Troubleshooting

Troubleshooting Guide - Solutions to common issues

  • Installation problems
  • Build errors
  • Database issues
  • Test failures
  • Platform-specific fixes

🌐 Testnet Setup

Testnet Guide - Complete testnet instructions

  • Multiple faucet methods
  • Freighter wallet setup
  • Contract deployment
  • Getting testnet USDC
  • Testing interactions

⚡ 30-Minute Setup Path

Minutes 0-5: Prerequisites

  1. Verify installed software:

    # Run verification script
./scripts/verify-setup.sh  # Linux/macOS
.\scripts\verify-setup.ps1  # Windows

  2. Install missing tools:

Minutes 5-10: Project Setup

# Clone repository
git clone https://github.com/YOUR_USERNAME/carbonledger.git
cd carbonledger

# Configure environment
cp .env.example .env
# Edit .env: Set DATABASE_URL and JWT_SECRET

# Setup Rust toolchain
rustup target add wasm32-unknown-unknown

Minutes 10-15: Database

# Create database
createdb carbonledger

# Run migrations
cd backend
npx prisma migrate dev
cd ..

Minutes 15-25: Dependencies

# Backend
cd backend && npm install && cd ..

# Frontend
cd frontend && npm install && cd ..

# Oracle
cd oracle && pip3 install -r requirements.txt && cd ..

# Contracts
cd contracts && cargo build --target wasm32-unknown-unknown --release && cd ..

Minutes 25-30: Run Tests

# Run all tests
./scripts/test-all.sh

# Expected: All tests pass ✓

🎯 Success Criteria

You're ready to contribute when:

  • ✅ All prerequisite software installed
  • ✅ Database created and migrations applied
  • ✅ All dependencies installed (npm, pip, cargo)
  • ✅ Contracts built successfully
  • ✅ All 30+ tests pass
  • ✅ Development servers start without errors

📋 Quick Reference

Essential Commands

# Verify setup
./scripts/verify-setup.sh

# Run all tests
./scripts/test-all.sh

# Start backend
cd backend && npm run start:dev

# Start frontend
cd frontend && npm run dev

# Build contracts
cd contracts && cargo build --target wasm32-unknown-unknown --release

# Run contract tests
cd contracts && cargo test

Common Issues

Issue Solution
PostgreSQL not running brew services start postgresql@16 (macOS)
sudo systemctl start postgresql (Linux)
Rust build fails xcode-select --install (macOS)
sudo apt install build-essential (Linux)
npm permission errors Use nvm or fix permissions
Database connection fails Check DATABASE_URL in .env
Tests fail Run ./scripts/verify-setup.sh

Full troubleshooting: TROUBLESHOOTING.md

🗺️ Project Structure

carbonledger/
├── contracts/          # Soroban smart contracts (Rust)
│   ├── carbon_registry/
│   ├── carbon_credit/
│   ├── carbon_marketplace/
│   └── carbon_oracle/
├── backend/           # NestJS API server
│   ├── src/
│   └── prisma/
├── frontend/          # Next.js 14 web app
│   ├── app/
│   ├── components/
│   └── lib/
├── oracle/            # Python oracle services
├── docs/              # Documentation
│   ├── QUICK_START.md
│   ├── TROUBLESHOOTING.md
│   ├── TESTNET_GUIDE.md
│   └── adr/          # Architecture decisions
└── scripts/           # Helper scripts
    ├── verify-setup.sh
    └── test-all.sh

🧪 Testing

Run All Tests

./scripts/test-all.sh

Individual Test Suites

# Rust contracts (30 tests)
cd contracts && cargo test

# Backend (NestJS)
cd backend && npm test

# Frontend (Next.js)
cd frontend && npm test

Test Coverage

Component Tests Coverage
carbon_registry 7 tests Core functionality
carbon_credit 10 tests Mint, retire, transfer
carbon_marketplace 7 tests List, buy, sell
carbon_oracle 6 tests Monitoring, prices
Backend Multiple API endpoints
Frontend Multiple Components

🌐 Testnet Development

Quick Testnet Setup

# 1. Generate and fund account
stellar keys generate alice --network testnet --fund

# 2. Deploy contracts
cd contracts
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/carbon_registry.wasm \
  --source alice \
  --network testnet

# 3. Update .env with contract IDs

Full guide: TESTNET_GUIDE.md

🤝 Contributing Workflow

1. Find an Issue

Browse Good First Issues

2. Create Branch

git checkout -b feat/your-feature-name

3. Make Changes

  • Write code
  • Add tests
  • Update documentation

4. Test Locally

./scripts/test-all.sh

5. Commit

git commit -m "feat: add serial number validation"

Follow Conventional Commits

6. Push and PR

git push origin feat/your-feature-name

Create Pull Request on GitHub

📖 Learning Resources

Architecture

Stellar/Soroban

Technologies

🆘 Getting Help

Documentation

  1. Check Troubleshooting Guide
  2. Review Contributing Guide
  3. Read Architecture Decisions

Community

When Asking for Help

Include:

  • Operating system and version
  • Node.js, Rust, Python versions
  • Full error message
  • Steps to reproduce
  • Output of ./scripts/verify-setup.sh

✨ What to Work On

Good First Issues

Perfect for new contributors:

  • Documentation improvements
  • Test coverage additions
  • Bug fixes with clear reproduction steps
  • UI/UX enhancements

Areas to Explore

  • Smart Contracts - Rust/Soroban development
  • Backend API - NestJS/TypeScript
  • Frontend - Next.js/React
  • Oracle Services - Python
  • Documentation - Markdown
  • Testing - Jest, Cargo test

🎉 You're Ready!

Once you've completed the setup:

  1. ✅ All tests pass
  2. ✅ Development servers start
  3. ✅ You understand the project structure
  4. ✅ You've read the contributing guidelines

Next steps:

📊 Setup Verification

Verified on:

  • ✅ macOS 13+ (Intel and Apple Silicon)
  • ✅ Ubuntu 22.04 LTS
  • ✅ Windows 11 with WSL2
  • ✅ Windows 11 native (PowerShell)

Average setup time:

  • Experienced developers: 15-20 minutes
  • First-time setup: 25-30 minutes
  • With troubleshooting: 30-45 minutes

🙏 Thank You!

Thank you for contributing to CarbonLedger! Every contribution helps build a more transparent and trustworthy carbon credit market.

Questions? Don't hesitate to ask in Discussions

Welcome to the team! 🌍