Skip to main content
We welcome contributions! Whether you want to fix a bug, add a feature, improve documentation, or help in any other way, your contribution is valuable to the Superset community.

​
Before You Start

Before contributing, please:
  1. Discuss your change: For significant changes, open an issue or start a discussion first
  2. Review the Code of Conduct: Follow our Code of Conduct in all interactions
  3. Check existing issues: Search for similar issues or PRs to avoid duplicates

​
Pull Request Process

​
1. Fork the Repository

Create a fork of the Superset repository:
  1. Go to github.com/superset-sh/superset
  2. Click the “Fork” button in the top-right corner
  3. Select your account as the destination

​
2. Clone Your Fork

git clone https://github.com/YOUR_USERNAME/superset.git
cd superset

​
3. Set Up Development Environment

Install dependencies: 
# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install Caddy (macOS)
brew install caddy

# Install GitHub CLI (macOS)
brew install gh
Configure environment: 
# Copy example env file
cp .env.example .env

# For local development, skip env validation
echo 'SKIP_ENV_VALIDATION=1' >> .env

# Set up Caddy config
cp Caddyfile.example Caddyfile
Install project dependencies: 
bun install

​
4. Create a Feature Branch

git checkout -b feature/amazing-feature
Use a descriptive branch name:
  • feature/add-workspace-templates
  • fix/terminal-paste-issue
  • docs/update-setup-guide

​
5. Make Your Changes

Write your code following our style guidelines. Run development server: 
bun run dev
This starts all dev servers including the desktop app.

​
6. Test Your Changes

# Run tests
bun test

# Type checking
bun run typecheck

# Linting
bun run lint

​
7. Commit Your Changes

Follow the Clean Code principles and the boy scout rule:
“Leave the code cleaner, not messier, than how you found it.” 
git add .
git commit -m "Add amazing feature"
Write clear, descriptive commit messages:
  • ✅ “Fix terminal paste handling for multi-line content”
  • ✅ “Add workspace template configuration support”
  • ❌ “fix bug”
  • ❌ “updates”

​
8. Push to Your Fork

git push origin feature/amazing-feature

​
9. Open a Pull Request

Create a pull request from your fork:
  1. Go to your fork on GitHub
  2. Click “Contribute” → “Open pull request”
  3. Fill in the PR description with:
    • Clear description of changes
    • Link to related issues (if applicable)
    • Screenshots or videos (for UI changes)
    • Testing steps
  4. Check the box “Allow edits from maintainers” - this speeds up the review process
  5. Request a review from one of the maintainers

​
10. Code Review

Maintainers will review your PR and may:
  • Request changes
  • Ask questions
  • Suggest improvements
  • Approve and merge
Be responsive to feedback and make requested changes promptly.

​
Code Style

Superset uses Biome for code formatting and linting.

​
Formatting & Linting

# Check for issues (no changes)
bun run lint

# Fix all auto-fixable issues
bun run lint:fix

# Format code only
bun run format

# Check formatting only (CI)
bun run format:check
Biome runs at root level for the entire monorepo:
  • biome check --write --unsafe = format + lint + organize imports + fix all
  • biome check = check only (no changes)
  • biome format = format only

​
Code Quality Guidelines

  1. Type safety: Avoid any unless absolutely necessary. Use proper TypeScript types
  2. Clean Code: Follow Clean Code principles
  3. Boy Scout Rule: Leave code cleaner than you found it
  4. Prefer gh CLI: Use GitHub CLI over raw git commands where possible
  5. Co-locate dependencies: Keep tests, hooks, utils next to the files using them

​
Monorepo Structure

Superset is a Bun + Turbo monorepo:

​
Apps

  • apps/web - Main web application (app.superset.sh)
  • apps/marketing - Marketing site (superset.sh)
  • apps/admin - Admin dashboard
  • apps/api - API backend
  • apps/desktop - Electron desktop application
  • apps/docs - Documentation site
  • apps/mobile - React Native mobile app (Expo)

​
Packages

  • packages/ui - Shared UI components (shadcn/ui + TailwindCSS v4)
  • packages/db - Drizzle ORM database schema
  • packages/auth - Authentication
  • packages/agent - Agent logic
  • packages/trpc - Shared tRPC definitions
  • packages/shared - Shared utilities
  • packages/mcp - MCP integration
  • packages/desktop-mcp - Desktop MCP server
  • packages/local-db - Local SQLite database
  • packages/durable-session - Durable session management
  • packages/email - Email templates/sending
  • packages/scripts - CLI tooling

​
Common Commands

# Development
bun dev                    # Start all dev servers
bun test                   # Run tests
bun build                  # Build all packages

# Code Quality
bun run lint               # Check for lint issues
bun run lint:fix           # Fix auto-fixable issues
bun run format             # Format code
bun run typecheck          # Type check all packages

# Maintenance
bun run clean              # Clean root node_modules
bun run clean:workspaces   # Clean all workspace node_modules

​
Testing Guidelines

  1. Write tests: Add tests for new features and bug fixes
  2. Run tests locally: Ensure all tests pass before submitting PR
  3. Co-locate tests: Place test files next to the code they test
# Run all tests
bun test

# Run tests in watch mode
bun test --watch

​
Database Changes

IMPORTANT: Never manually edit files in packages/db/drizzle/. These are auto-generated. To create a database migration:
  1. Modify schema files in packages/db/src/schema/
  2. Generate migration: 
    bunx drizzle-kit generate --name="migration_name_snake_case"
  3. Never run migrations yourself - let maintainers handle this

​
Documentation

Documentation improvements are always welcome!
  • Docs site: Located in apps/docs
  • README: Main README at repository root
  • Code comments: Add JSDoc comments for complex functions
To run the docs site locally: 
bun run dev:docs

​
Community Guidelines

We follow the Contributor Covenant Code of Conduct.

​
Our Standards

Examples of behavior that contributes to a positive environment:
  • Demonstrating empathy and kindness
  • Being respectful of differing opinions
  • Giving and gracefully accepting constructive feedback
  • Focusing on what’s best for the community
Examples of unacceptable behavior:
  • Sexualized language or imagery
  • Trolling, insulting, or derogatory comments
  • Public or private harassment
  • Publishing others’ private information

​
Enforcement

Instances of unacceptable behavior may be reported to founders@superset.sh.

​
Getting Help

If you need help with contributing:

​
Recognition

All contributors are recognized in our README and release notes. Thank you for making Superset better!

​
License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.