Conventional Commits

Spotlight uses Conventional Commits for commit messages. This allows us to automatically generate changelogs and determine version bumps.

Commit Message Format

Each commit message should follow this format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Type	Description	Version Bump
`feat`	A new feature	Minor
`fix`	A bug fix	Patch
`docs`	Documentation only changes	Patch
`refactor`	Code change that neither fixes a bug nor adds a feature	Patch
`perf`	Performance improvement	Patch
`test`	Adding or updating tests	Patch
`chore`	Maintenance tasks, dependencies, etc.	Patch
`ci`	CI/CD changes	Patch
`build`	Build system changes	Patch

Breaking Changes

For breaking changes, add ! after the type/scope:

feat!: remove deprecated API

BREAKING CHANGE: The old API has been removed.

This will trigger a major version bump.

Scopes

Scopes are optional but help categorize changes:

ui - UI components
server - Sidecar server
cli - CLI commands
electron - Electron app
mcp - MCP server

Examples

# New feature
feat(ui): add dark mode toggle

# Bug fix
fix(server): handle empty envelopes correctly

# Breaking change
feat(cli)!: change default port to 8970

# Documentation
docs: update installation guide

# Chore (won't appear in changelog by default)
chore: update dependencies

Changelog Preview

When you open a PR, a bot will automatically comment with a preview of how your changes will appear in the changelog. This helps you verify your commit messages are correct.

Skipping Changelog

If your PR shouldn’t appear in the changelog (e.g., internal refactoring), you can:

Add #skip-changelog anywhere in your commit message or PR description
Add the skip-changelog label to your PR