Contributing

​

Before You Start

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

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 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

# 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

bun install

​

4. Create a Feature Branch

git checkout -b feature/amazing-feature

• feature/add-workspace-templates
• fix/terminal-paste-issue
• docs/update-setup-guide

​

5. Make Your Changes

bun run dev

​

6. Test Your Changes

# Run tests
bun test

# Type checking
bun run typecheck

# Linting
bun run lint

​

7. Commit Your Changes

“Leave the code cleaner, not messier, than how you found it.”

git add .
git commit -m "Add amazing feature"

• ✅ “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

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

• Request changes
• Ask questions
• Suggest improvements
• Approve and merge

​

Code Style

​

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 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

​

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

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

• Docs site: Located in apps/docs
• README: Main README at repository root
• Code comments: Add JSDoc comments for complex functions

bun run dev:docs

​

Community Guidelines

​

Our Standards

• Demonstrating empathy and kindness
• Being respectful of differing opinions
• Giving and gracefully accepting constructive feedback
• Focusing on what’s best for the community

• Sexualized language or imagery
• Trolling, insulting, or derogatory comments
• Public or private harassment
• Publishing others’ private information

​

Enforcement

​

Getting Help

• Discord: Join Discord for real-time help
• Discussions: Ask in GitHub Discussions
• Issues: Check existing issues for similar questions

​

Recognition

​

License