Contributing

Stasis is open source and contributions are welcome. This page explains how to set up your development environment and submit changes.

Prerequisites

• Go 1.24+ — Install Go
• Bun or Node.js 18+ — Install Bun (recommended) or Node.js
• Docker and Docker Compose — Install Docker
• Git — Install Git

Setting Up Your Development Environment

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/stasis.git
cd stasis

# Add the upstream remote
git remote add upstream https://github.com/get-stasis/stasis.git

2. Start the Database

docker compose up -d postgres

3. Configure Environment

cp configs/.env.example .env

Edit .env and set at least:

STASIS_DB_PASSWORD=dev-password
STASIS_OIDC_JWT_SECRET=dev-jwt-secret-at-least-32-characters-long

4. Run the API Server

# Install Go dependencies
go mod download

# Run the server
go run ./cmd/server

The API server starts at http://localhost:8080.

5. Run the Web Frontend

In a separate terminal:

cd web
bun install
bun run dev

The frontend starts at http://localhost:3000.

Making Changes

Branch Naming

Create a branch for your changes:

git checkout -b feature/my-new-feature
# or
git checkout -b fix/my-bug-fix

Code Style

• Go: Follow standard Go conventions. Run go fmt ./... before committing.
• TypeScript: Follow the existing code style. The project uses Biome for linting.

Commit Messages

Use conventional commit format:

feat: add new feature
fix: fix a bug
docs: update documentation
chore: maintenance tasks

Testing

Run tests before submitting:

# Go tests
go test ./...

# Frontend build check
cd web && bun run build

See Testing for more details.

Submitting a Pull Request

1. Push your branch to your fork:

   git push origin feature/my-new-feature

2. Go to the Stasis repository on GitHub

3. Click "New Pull Request"

4. Select your branch and fill in the PR template

5. Wait for review

PR Guidelines

• Keep PRs focused — one feature or fix per PR
• Include a clear description of what changed and why
• Link any related issues
• Make sure CI passes

Reporting Bugs

Found a bug? Open an issue with:

• A clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Your environment (OS, Go version, etc.)

Requesting Features

Have an idea? Open a discussion with:

• The problem you're trying to solve
• Your proposed solution
• Any alternatives you considered

Code of Conduct

Be respectful and constructive. We're all here to build something useful together.

Next Steps