Skip to main content

Git Conventions

Branch Naming​

All branches must follow this pattern:

  • feature/description-here - New features
  • bugfix/description-here - Bug fixes
  • hotfix/description-here - Urgent production fixes
  • release/version-number - Release branches
  • chore/description-here - Maintenance tasks

Examples​

  • ✅ feature/add-team-invitations
  • ✅ bugfix/fix-login-redirect
  • ✅ hotfix/patch-security-vulnerability
  • ❌ Feature/AddTeamInvitations (wrong case)
  • ❌ add-team-invitations (missing type prefix)

Commit Messages​

We use Conventional Commits format for standardized commit messages and automatic changelog generation.

Making Commits​

Instead of using git commit, use the interactive commitizen prompt:

# Stage your changes first
git add .

# Use commitizen for interactive commit
pnpm run commit

This will guide you through creating a properly formatted commit message.

Manual Commit Format​

If you prefer to write commits manually, follow this format:

<type>(scope): <description>

[optional body]

[optional footer(s)]

Types​

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

Scopes​

  • web: Web application
  • dev-tool: Development tools
  • e2e: End-to-end tests
  • ui: UI components
  • supabase: Database/backend
  • auth: Authentication
  • billing: Billing system
  • admin: Admin features
  • i18n: Internationalization
  • shared: Shared packages
  • config: Configuration
  • deps: Dependencies
  • repo: Repository-wide changes
  • tooling: Development tooling

Examples​

  • ✅ feat(auth): add two-factor authentication
  • ✅ fix(billing): resolve subscription update issue
  • ✅ docs(readme): update installation instructions
  • ✅ chore(deps): update dependencies
  • ❌ Added new feature (missing type and scope)

Changelog Generation​

The changelog is automatically generated from your conventional commit messages and preserves a header template with project information.

Automatic Generation​

The changelog is automatically updated when you create new versions:

# Create a patch version and update changelog
pnpm run version:patch

# Create a minor version and update changelog  
pnpm run version:minor

# Create a major version and update changelog
pnpm run version:major

Manual Generation​

You can also generate the changelog manually:

# Update changelog with new entries since last release
pnpm run changelog

The changelog generation preserves the header template (defined in CHANGELOG.template.md) which includes:

  • Project description and conventions used
  • How to read version numbers
  • Types of changes explanation

Customizing the Template​

To customize the changelog header, edit the CHANGELOG.template.md file. This template will be preserved whenever the changelog is generated.

Quick Start​

  1. Create branch: pnpm branch:create
  2. Make changes and stage them: git add .
  3. Commit using commitizen: pnpm commit (recommended)
    • Or manual commit: git commit -m "type(scope): message"
  4. Push: git push

💡 Always use pnpm commit - This ensures your commits follow the correct format and prevents validation errors in CI.

CI Validation​

The CI pipeline automatically validates:

  • Branch names follow the naming convention
  • All commit messages follow conventional commit format

Make sure all commits in your PR follow the conventional commit format before creating the pull request.

Benefits​

  1. Consistency: All commits follow the same format
  2. Automation: Automatic changelog generation
  3. Semantic Versioning: Clear version bumps based on commit types
  4. Better Collaboration: Clear commit history for team members
  5. Release Notes: Automatic generation of release notes from commits