Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (114 loc) · 4.85 KB

CONTRIBUTING.md

File metadata and controls

170 lines (114 loc) · 4.85 KB
Raw

Contributing to NebGov

Thank you for contributing to NebGov, the permissionless governance framework for Stellar.

Prerequisites

  • Rust (stable toolchain) with wasm32-unknown-unknown target
  • Stellar CLI (stellar) for contract building and testing
  • Node.js 20+ with pnpm 9+
  • Git

Install Prerequisites

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

# Stellar CLI
cargo install --locked stellar-cli

# Node.js (via nvm)
nvm install 20
npm install -g pnpm@9

Local Setup

git clone https://github.com/nebgov/nebgov && cd nebgov

# Build all Soroban contracts
stellar contract build

# Install JS dependencies
pnpm install

# Build the SDK
pnpm build:sdk

Running Tests

# Rust contract tests
cargo test --workspace

# SDK unit tests
pnpm test:sdk

# Frontend tests
pnpm test:app

# E2E tests (requires running app)
cd app && npx playwright test

Security Scanning

We use CoinFabrik Scout to automatically scan our Soroban contracts for security vulnerabilities.

Local Usage

To run Scout locally, you first need to install the scout-audit tool:

cargo install cargo-scout-audit

Then, run the scanner from the repository root:

cargo scout-audit --output-format html

This will generate an audit_report.html file with the results.

Interpreting Results

  • Critical/High: These findings will fail the CI build and must be addressed before merging.
  • Medium/Low/Info: These findings do not fail the CI but should be reviewed and fixed if applicable.

Suppressing False Positives

If a finding is confirmed as a false positive, it can be suppressed in .scout.toml at the repository root. Each suppression must include a justification:

[[suppressions]]
detector = "detector_name"
reason = "Suppressed: [reason] — [date] — [author]"

Project Structure

Directory Description
contracts/governor Core governance contract (Rust/Soroban)
contracts/timelock Delayed execution controller
contracts/token-votes Voting power with checkpointing
contracts/governor-factory Permissionless governor deployer
contracts/treasury Multi-sig treasury
sdk/ TypeScript SDK (@nebgov/sdk)
app/ Next.js governance dashboard
docs/ Architecture docs and ADRs

How to Contribute

1. Find an issue

Browse open issues. Each issue is tagged with:

  • complexity: trivial - small, well-scoped change
  • complexity: medium - moderate implementation work
  • complexity: high - significant feature or architectural change

When opening a new issue, please choose one of the repository's issue templates so your report includes all required details.

Issues tagged good first issue are recommended for first-time contributors.

Branch Naming

  • feat/issue-<number>-<description> for features
  • fix/issue-<number>-<description> for bug fixes
  • docs/issue-<number>-<description> for documentation

Commit Messages

Use imperative mood with conventional prefixes:

  • feat: add vote delegation
  • fix: correct quorum calculation
  • docs: update architecture diagram
  • test: add governor edge cases
  • chore: update dependencies

Pull Request Process

  1. Fork the repo and create a branch from main
  2. Make your changes with tests for new features
  3. Ensure all CI checks pass: cargo test --workspace && pnpm test:sdk
  4. Update docs if you changed any public API
  5. Open a PR referencing the issue: Closes #<number>
  6. Wait for maintainer review. Note that reviewers are automatically assigned based on our CODEOWNERS configuration. For more details on our branch protection rules, see Branch Protection.

Security Issues

If you find a security vulnerability, do not open a public issue. Follow the private reporting process in SECURITY.md instead.

Code Standards

Rust (contracts)

  • Format with cargo fmt
  • No unsafe code
  • All public functions must have doc comments
  • Tests live in #[cfg(test)] modules

TypeScript (SDK + frontend)

  • Strict TypeScript, no any types
  • Run pnpm lint before pushing
  • Use named exports

Issue Scope

Each issue is scoped to be completable in under one week by a single contributor. If you find an issue is larger than expected, comment on it so it can be split.

Questions?

Open a discussion on GitHub or comment on the relevant issue.