Contributing

How to propose a change to Appstrate: setup, branches, commits, and the pull request process.

Thanks for your interest in contributing. This page is the short version. The canonical reference is CONTRIBUTING.md at the root of the repository, and when the two differ, the repository wins. Larger changes follow the process in GOVERNANCE.md.

All participants are expected to follow the Code of Conduct.

Getting help

Discord: quick questions and real-time chat with maintainers.
GitHub Issues: bug reports and feature requests, through the bug report and feature request templates.

Ways to contribute

Code is one path among several. Documentation fixes, translations (the UI is French and English, in apps/web/src/locales/), triage, design feedback, and answering questions on Discord all count.

Development setup

You need Bun 1.3.14 or newer. Docker (with Compose v2) is only needed to work on container execution or to run the full stack.

git clone https://github.com/<your-username>/appstrate.git
cd appstrate
bun install
cp .env.example .env
bun run dev          # http://localhost:3000, embedded database, no Docker

That is Tier 0: PGlite, filesystem storage, in-memory queues, agents as host subprocesses. It is enough for most frontend, API, and backend work. bun run setup brings up the full stack (PostgreSQL, Redis, S3-compatible storage, Docker execution) when you need it. Changes under runtime-pi/ need bun run build-runtime, which rebuilds the agent and sidecar images together. The infrastructure tiers are described in Progressive infrastructure, and the layout of the code in Architecture.

Useful commands:

Command	What it does
`bun run check`	The quality gate: typecheck, lint, format, OpenAPI, and the repository's other verification steps
`bun test apps/api/test/unit/`	Fast unit tests with no database. Run only the tests your change touches
`bun run test:tier0`	The whole suite on PGlite, split across processes, no Docker
`bun run verify:openapi`	Validates the OpenAPI document against the code

Branches and commits

Branch from main:

feat/short-description: new features
fix/short-description: bug fixes
docs/short-description: documentation
refactor/short-description: refactoring

Commit messages follow Conventional Commits, enforced by commitlint:

feat: add webhook retry configuration
fix: prevent duplicate cron runs
docs: update API overview table
refactor: extract credential validation into service

Commit signing (GPG or SSH) is recommended, not required.

Pull requests

Create a branch from main.
Keep commits focused, and do not bundle unrelated changes.
Run bun run check and the tests that cover your change.
Open a pull request against main with a clear description.
Sign the CLA on your first pull request. The bot walks you through it.
Wait for CI and review. Pull requests are squash-merged after approval.

A reviewer will look for:

The quality gate passes, and the change matches its description.
New behavior has tests.
API changes update the OpenAPI spec in the same pull request. The OpenAPI document is the source of truth for the API.
A change that alters behavior updates the matching page in docs/site/. This documentation lives in the repository, next to the code.

Response times

Goals, not guarantees: issue acknowledgment within 5 business days, bug triage within 10 business days, first pull request review within 10 business days, and security reports within 48 hours. Report security issues privately, as described in SECURITY.md.

License

By contributing, you agree that your contributions are licensed under the Apache License 2.0. The exception is packages/module-ee, which carries its own source-available license.