Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
340 lines (242 loc) · 8.95 KB

CONTRIBUTING.md

File metadata and controls

340 lines (242 loc) · 8.95 KB
Raw

Contributing to TaskBounty

Thank you for your interest in contributing to TaskBounty — a decentralized task and reward board built on Stellar using Soroban smart contracts. This document covers everything you need to get started.

Table of Contents

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive, actionable feedback
  • Communicate early if you're blocked — create a draft PR rather than going silent
  • Maximum ETA for claimed issues: 48 hours. After 24 hours, a draft PR or progress update is expected

Before You Start

  1. Check open issues to avoid duplicate work
  2. Comment on the issue you want to work on and wait for assignment
  3. Read SETUP.md to get your environment ready
  4. Read CONTRACT_API.md to understand the contract interface

CI checks

Pull requests to main run:

  • Frontend CI — lint + build (FRONTEND_CI_GUIDE.md)
  • Contract CI — cargo fmt, build, test, clippy
  • Dependency vulnerability scan — pnpm audit + cargo audit with downloadable reports (DEPENDENCY_SCANNING.md)

Run the dependency scanners locally before opening a PR that changes lockfiles:

./scripts/run-dependency-scan.sh

Frontend HTTP security headers are configured in Next.js and documented in SECURITY_HEADERS.md. Verify locally before changing header policy:

cd frontend && pnpm test:security-headers
# or full build + live header check:
./scripts/test-security-headers.sh

Development Setup

See SETUP.md for full instructions. Quick summary:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add WebAssembly target
rustup target add wasm32-unknown-unknown

# Install Stellar CLI
cargo install --locked stellar-cli --features opt

# Clone and build
git clone https://github.com/<your-username>/Task-Bounty.git
cd Task-Bounty/contract
stellar contract build

# Run tests
cargo test

Branch Naming Conventions

<type>/<short-description>
Type Use for
feature/ New functionality
fix/ Bug fixes
docs/ Documentation only changes
refactor/ Code restructuring without behavior change
test/ Adding or updating tests
chore/ Tooling, CI, dependency updates

Examples:

feature/reputation-system
fix/deadline-validation
docs/contract-api
refactor/storage-helpers

Commit Message Standards

Follow Conventional Commits:

<type>: <short description>

[optional body]

Types: feat, fix, docs, test, refactor, chore

Examples:

feat: add milestone-based task support
fix: prevent double-submission from same contributor
docs: add contract API reference
test: add dispute resolution edge cases
refactor: extract token transfer logic to helper
chore: update soroban-sdk to 21.0.0

Rules:

  • Use imperative mood: "add" not "added"
  • Keep subject line under 72 characters
  • Reference issue numbers in the body: Closes #42

Development Workflow

1. Fork and clone

git clone https://github.com/<your-username>/Task-Bounty.git
cd Task-Bounty
git remote add upstream https://github.com/<org>/Task-Bounty.git

2. Create a branch

git checkout -b feature/your-feature-name

3. Make changes

Smart contract changes (contract/):

  • Write clean, modular Rust code
  • Add doc comments (///) to all public functions
  • Follow the existing module structure (task.rs, submission.rs, etc.)
  • Run cargo clippy and fix all warnings before committing

Frontend changes (frontend/):

  • Maximum 150 lines per component
  • Use TypeScript types — no any
  • Match the existing component structure
  • Ensure responsive design

4. Write tests

All contract changes require tests in src/test.rs:

#[test]
fn test_your_feature() {
    let env = Env::default();
    // setup
    // execute
    // assert
}

5. Verify

# Contract
cargo test
cargo clippy -- -D warnings

# Frontend
cd frontend
npm run lint
npm run build

6. Commit and push

git add <specific-files>
git commit -m "feat: your feature description"
git push origin feature/your-feature-name

Pull Request Requirements

Title

Same format as commit messages: feat: add reputation system

Description must include

## What
Brief description of the changes.

## Why
What problem does this solve? Link the issue: Closes #<issue-number>

## How
Key implementation decisions or approach.

## Testing
What tests were added or modified?

## Breaking Changes
List any breaking changes (or "None").

Checklist before requesting review

A PR template with the full checklist is automatically loaded when you open a PR on GitHub (see .github/pull_request_template.md). The checklist covers:

  • Tests added/updated and passing (cargo test)
  • No compiler warnings (cargo clippy)
  • Documentation updated if public API changed
  • Dependency changes reviewed against CI scan reports / Dependabot (see DEPENDENCY_SCANNING.md)
  • Frontend security header changes verified (pnpm test:security-headers / see SECURITY_HEADERS.md)
  • PR description complete with issue reference
  • Branch is up to date with main
  • PR title follows Conventional Commits format
  • PR description complete with issue reference (Closes #<issue-number>)
  • Tests added/updated and passing (cargo test / npm run build)
  • No compiler warnings (cargo clippy -- -D warnings)
  • Code formatted (cargo fmt / ESLint)
  • Documentation updated if public API changed
  • CONTRACT_API.md updated if contract interface changed
  • require_auth() called on all state-changing contract operations
  • Events emitted for all state changes (smart contract PRs)
  • Screenshots/recordings included for UI changes (frontend PRs)

Scope

Keep PRs focused. One logical change per PR. Large features should be split into smaller, reviewable pieces.

Issue Reporting Guidelines

Bug reports

Use the Bug Report template and include:

  1. Description — What happened vs. what you expected
  2. Steps to reproduce — Minimal steps to trigger the bug
  3. Environment — OS, Rust version (rustc --version), Stellar CLI version (stellar --version)
  4. Logs/errors — Paste relevant error output in a code block

Feature requests

Use the Feature Request template and include:

  1. Problem — What pain point does this address?
  2. Proposed solution — How should it work?
  3. Alternatives — Other approaches you considered
  4. Scope — Is this a contract change, frontend change, or both?

Getting help

If you're stuck during implementation:

  1. Create a draft PR with your current progress
  2. Tag the maintainer in the PR description
  3. Describe the specific blocker
  4. Do not ask for help in issue comments

Code Review Expectations

For contributors

  • Respond to review comments within 24 hours
  • Don't push force-push over a review in progress — add new commits
  • If you disagree with feedback, explain your reasoning; don't just ignore it
  • Mark resolved threads as resolved

For reviewers

  • Review within 48 hours of assignment
  • Test contract logic locally for non-trivial changes
  • Focus on correctness, security, and maintainability — not style preferences
  • Approve explicitly when ready; don't leave PRs in limbo

Review focus areas for Soroban contracts

  • require_auth() called on all state-changing operations
  • No unintended token transfer paths
  • Correct status transition guards
  • Events emitted for all state changes
  • Storage keys don't collide
  • Deadline and input validation complete

Code Style

Rust / Soroban

  • Use /// doc comments on all public functions
  • Follow rustfmt formatting (cargo fmt)
  • Prefer explicit error types (Error enum) over panics
  • Use symbol_short! for event topics

TypeScript / Next.js

  • Use functional components with TypeScript
  • Name components in PascalCase, files matching component name
  • Co-locate component-specific types in the same file
  • Use const arrow functions for event handlers

License

By contributing, you agree your contributions will be licensed under the MIT License.