Grey Haven Commit Message Format

Follow Grey Haven Studio's actual commit message standards, enforced by commitlint configuration from production templates.

Format Structure

<type>(<scope>): <subject>

[optional body]

[optional footer]

CRITICAL Rules (Commitlint Enforced)

These rules are automatically enforced by commitlint:

1. Header max length: 100 characters (NOT 72 or 50!)
2. Type: REQUIRED and must be lowercase
3. Subject: REQUIRED and lowercase (NO sentence-case, start-case, pascal-case, or upper-case)
4. Body: blank line before (if included)
5. Footer: blank line before (if included)

Commit Types

Use exactly these types from Grey Haven's commitlint configuration:

Type	Use Case	Example
feat	New feature for the user	feat(auth): add magic link authentication
fix	Bug fix for the user	fix(api): resolve race condition in order processing
docs	Documentation changes only	docs(readme): update TanStack Start setup guide
style	Code style changes (formatting) - no logic changes	style: apply Prettier to all TypeScript files
refactor	Code refactoring - neither fixes a bug nor adds a feature	refactor(repositories): simplify user query logic
test	Adding or updating tests	test(auth): add integration tests for OAuth flow
chore	Maintenance tasks, dependency updates	chore(deps): upgrade React to v19.1.0
perf	Performance improvements	perf(db): add composite index on user_id and created_at
ci	CI/CD configuration changes	ci: add Vitest coverage threshold check
build	Build system or dependency changes	build: configure bun for monorepo
revert	Revert a previous commit	revert: feat(auth): add OAuth authentication

Any other type will be REJECTED by commitlint.

Subject Line Rules

Requirements

• Max length: 100 characters (header includes type + scope + subject)
• Case: lowercase ONLY - NO capitals anywhere
• Format: imperative mood - "add" not "added" or "adds"
• No period at the end
• Be specific about what changed

Calculating Header Length

feat(auth): add OAuth provider for Google authentication
^---------^ = 9 chars (type + scope)
            ^----------------------------------------^ = 45 chars (subject)
Total: 54 characters (within 100 limit ✅)

Good Examples

feat(auth): add password reset with email verification
fix(api): prevent duplicate user email registrations
docs: update API authentication guide with examples
refactor(utils): simplify date formatting helper functions
perf(db): add composite index on user_id and created_at

Bad Examples (Fail Commitlint)

❌ feat(auth): Add OAuth provider     # Uppercase 'A' (violates subject-case)
❌ Fix bug in API                      # Uppercase 'F' (violates subject-case)
❌ feat: add new feature.              # Period at end
❌ WIP                                 # Not a valid type
❌ added new endpoint                  # Missing type
❌ feat(api): Added endpoint and updated schema and added validation and wrote tests and updated docs
   # Exceeds 100 characters

Scope Guidelines

The scope should indicate which part of the codebase is affected:

Frontend Scopes (TanStack Start/React)

• auth, ui, forms, layout, routes, queries, db, server

Backend Scopes (FastAPI/Python)

• api, models, repositories, services, schemas, db, utils, config

Infrastructure Scopes

• deps, docker, deploy, scripts, ci, hooks

Scope is optional - omit if change affects multiple areas or is global.

Body (Optional)

Use the body to provide additional context when needed.

When to Include a Body

• Explaining why the change was made (motivation)
• Describing implementation approach that isn't obvious
• Noting breaking changes or important considerations
• Referencing related Linear issues or GitHub issues
• Listing multiple changes in a larger commit

Body Format

• Blank line REQUIRED between subject and body
• Wrap at 90 characters per line
• Use bullet points for lists (markdown format)
• Write in present tense, imperative mood

Footer (Optional)

Breaking Changes (CRITICAL)

Start with BREAKING CHANGE: followed by description:

feat(api): migrate user IDs to UUID format

Change user ID format from sequential integers to UUIDs for better
scalability and security in multi-tenant architecture.

BREAKING CHANGE: User IDs are now UUIDs instead of sequential integers.
All API clients must update to handle UUID format. Database migration
required before deploying this change.

Linear Issue References

Fixes GREY-456
Related to GREY-123

GitHub Issue References

Fixes #234
Closes #456
Related to #789

Supporting Documentation

All supporting files are under 500 lines per Anthropic best practices:

• examples/ - Complete commit message examples

  • frontend-examples.md - TypeScript/TanStack examples
  • backend-examples.md - Python/FastAPI examples
  • multi-tenant-examples.md - Multi-tenant patterns
  • breaking-change-examples.md - Breaking changes
  • INDEX.md - Examples navigation

• reference/ - Configuration and rules

  • commitlint-config.md - Commitlint configuration
  • scope-reference.md - Detailed scope guidelines
  • validation.md - Pre-commit validation
  • INDEX.md - Reference navigation

• templates/ - Copy-paste ready templates

  • simple-commit.txt - Simple commit template
  • with-body.txt - Commit with body template
  • breaking-change.txt - Breaking change template

• checklists/ - Pre-commit validation

  • commit-checklist.md - Pre-commit checklist

Quick Checklist

Before committing, verify:

• Type is one of: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
• Type is lowercase
• Subject is lowercase (NO capitals anywhere)
• Subject uses imperative mood ("add" not "added")
• Full header is under 100 characters
• Subject doesn't end with a period
• Body has blank line after subject (if included)
• Breaking changes start with "BREAKING CHANGE:"

When to Apply This Skill

Use this skill when:

• Creating git commits in Grey Haven projects
• Reviewing pull requests and commit messages
• Setting up commit message templates
• Configuring commitlint for new projects
• Writing release notes from commit history
• Squashing commits before merging

Template Reference

These standards come from Grey Haven's actual templates:

• cvi-template: TanStack Start + React 19 (commitlint.config.cjs)
• cvi-backend-template: FastAPI + SQLModel (same commitlint config)

Critical Reminders

1. Header max: 100 characters (NOT 72 or 50!)
2. Subject: lowercase ONLY (NO capitals anywhere)
3. Types: exact match required (feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert)
4. Body/footer: blank line before (enforced by commitlint)
5. Breaking changes: use BREAKING CHANGE: prefix
6. Linear issues: reference as GREY-123
7. Multi-tenant: mention tenant_id when relevant
8. Python projects: activate .venv before committing
9. Pre-commit hooks: will validate format automatically
10. Squash merges: preferred for main branch