Skip to main content

Contributing to STOA

Whether you're fixing a typo or building a major feature, every contribution matters. This guide helps you get started.

Quick Start​

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/stoa.git
cd stoa

# 2. Pick a component
cd control-plane-api   # Python 3.11, FastAPI
cd portal              # React 18, TypeScript, Vite
cd control-plane-ui    # React 18, TypeScript, Vite
cd stoa-gateway        # Rust, Tokio, axum

# 3. Install dependencies
make setup             # or per-component: npm install / pip install -e ".[dev]"

# 4. Run tests
make test              # all components

Find Something to Work On​

Good First Issues​

We maintain a curated list of beginner-friendly issues:

Each issue includes:

  • A clear description of what to do
  • Expected outcome
  • Relevant files and commands
  • Difficulty rating (beginner / intermediate / advanced)

Other Ways to Contribute​

TypeWhereImpact
Bug reportsGitHub IssuesHelp us find problems
Documentationstoa-docsHelp others learn
Translationsi18n/ directoriesReach more users
Code reviewsOpen PRsImprove quality
Community helpDiscord #helpSupport new users

Development Setup​

Prerequisites​

ToolVersionRequired For
Python3.11+API, MCP Gateway, CLI
Node.js20+Portal, Console UI
RuststableSTOA Gateway
DockerlatestLocal services
kubectllatestK8s development (optional)

Per-Component Setup​

Control Plane API (Python)​

cd control-plane-api
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ --cov=src -q

Portal or Console UI (TypeScript)​

cd portal  # or control-plane-ui
npm install
npm run dev          # Dev server
npm run test -- --run  # Tests
npm run lint         # Lint check

STOA Gateway (Rust)​

cd stoa-gateway
cargo build
cargo test
cargo clippy --all-targets --all-features

PR Workflow​

1. Create a Branch​

git checkout -b feat/add-rate-limiting   # or fix/, docs/, test/

Branch prefixes: feat/, fix/, docs/, refactor/, test/, chore/

2. Make Changes​

  • Keep PRs focused — one concern per PR
  • Add tests for new functionality
  • Update documentation if behavior changes

3. Commit with Conventional Commits​

git commit -s -m "feat(api): add rate limiting per tenant"

Format: type(scope): description

TypeUse For
featNew feature
fixBug fix
docsDocumentation
testTests
refactorCode restructuring
choreMaintenance

The -s flag adds your DCO sign-off (required).

4. Run Quality Checks​

# Python
ruff check . && black --check . && pytest tests/ -q

# TypeScript
npm run lint && npm run format:check && npm run test -- --run

# Rust
cargo fmt --check && cargo clippy --all-targets && cargo test

5. Submit Your PR​

git push -u origin HEAD

Then open a PR on GitHub. Include:

  • What changed and why
  • How to test it
  • Link to the related issue (if any)

Code Style​

LanguageFormatterLinterLine Length
Pythonblackruff120 (API), 100 (others)
TypeScriptprettiereslint100
Rustcargo fmtclippystandard

License Headers​

All source files need an Apache 2.0 header:

# Copyright 2026 STOA Platform Authors
# SPDX-License-Identifier: Apache-2.0

Run python scripts/add-license-headers.py --check . to verify.

Testing​

Every PR should include tests. We use:

ComponentFrameworkRun
APIpytest + pytest-asynciopytest tests/ -q
Portal / UIvitest + React Testing Librarynpm run test -- --run
Gatewaycargo testcargo test --all-features
E2EPlaywright + BDDnpx playwright test

Getting Help​

Recognition​

All contributors are recognized in CONTRIBUTORS.md and release notes. Contributions also earn points toward our Rewards Program.

See the full CONTRIBUTING.md on GitHub for additional details.