> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventional Commits

> Understanding how HelixCommit categorizes commits

## Overview

GitReleaseGen automatically categorizes commits based on the [Conventional Commits](https://www.conventionalcommits.org/) specification. This structured format makes release notes more organized and meaningful.

<Info>
  While GitReleaseGen works with any commit format, using Conventional Commits produces the best results with automatic categorization and breaking change detection.
</Info>

## Conventional Commits format

The basic structure of a Conventional Commit:

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

[optional body]

[optional footer(s)]
```

### Example commits

<CodeGroup>
  ```bash Feature theme={}
  feat(auth): add OAuth2 authentication

  Implements OAuth2 flow with JWT tokens for secure user sessions.
  Supports multiple providers including Google and GitHub.
  ```

  ```bash Bug fix theme={}
  fix(api): resolve rate limiting issues

  Fixed exponential backoff calculation that was causing
  unnecessary delays in retry attempts.
  ```

  ```bash Breaking change theme={}
  feat(api)!: migrate to REST API v2

  BREAKING CHANGE: The v1 API endpoints are removed.
  Clients must migrate to v2 endpoints.
  ```

  ```bash Documentation theme={}
  docs: update installation guide

  Added troubleshooting section and clarified
  Python version requirements.
  ```
</CodeGroup>

## Commit types

GitReleaseGen recognizes these commit types and organizes them into sections:

<ResponseField name="feat" type="features">
  **New features or capabilities**

  ```bash theme={}
  feat(ui): add dark mode toggle
  feat: implement user dashboard
  feat(api): add rate limiting
  ```

  Appears in: **Features** section
</ResponseField>

<ResponseField name="fix" type="bug fixes">
  **Bug fixes and error corrections**

  ```bash theme={}
  fix(parser): handle multiline commit messages
  fix: resolve memory leak in background tasks
  fix(ui): correct button alignment
  ```

  Appears in: **Bug Fixes** section
</ResponseField>

<ResponseField name="docs" type="documentation">
  **Documentation changes**

  ```bash theme={}
  docs: update API reference
  docs(readme): add contributing guidelines
  docs: fix typos in quickstart guide
  ```

  Appears in: **Documentation** section
</ResponseField>

<ResponseField name="style" type="style">
  **Code style changes (formatting, whitespace)**

  ```bash theme={}
  style: format code with prettier
  style(css): improve button styling
  ```

  Appears in: **Style** section
</ResponseField>

<ResponseField name="refactor" type="refactoring">
  **Code refactoring without changing behavior**

  ```bash theme={}
  refactor(auth): simplify token validation
  refactor: extract duplicate logic to utility
  ```

  Appears in: **Refactoring** section
</ResponseField>

<ResponseField name="perf" type="performance">
  **Performance improvements**

  ```bash theme={}
  perf(db): optimize query performance
  perf: add caching layer for API responses
  ```

  Appears in: **Performance** section
</ResponseField>

<ResponseField name="test" type="tests">
  **Test additions or updates**

  ```bash theme={}
  test(api): add integration tests
  test: improve coverage for edge cases
  ```

  Appears in: **Tests** section
</ResponseField>

<ResponseField name="build" type="build">
  **Build system and dependency changes**

  ```bash theme={}
  build: upgrade to webpack 5
  build(deps): bump pytest from 7.0 to 8.0
  ```

  Appears in: **Build** section
</ResponseField>

<ResponseField name="ci" type="ci/cd">
  **CI/CD configuration changes**

  ```bash theme={}
  ci: add GitHub Actions workflow
  ci(docker): optimize build caching
  ```

  Appears in: **CI/CD** section
</ResponseField>

<ResponseField name="chore" type="chores">
  **Maintenance tasks and miscellaneous**

  ```bash theme={}
  chore: update dependencies
  chore(release): bump version to 2.0.0
  ```

  Appears in: **Chores** section
</ResponseField>

## Scopes

Scopes provide additional context about what part of the codebase changed:

```bash theme={}
feat(api): add authentication endpoint
fix(ui): resolve button styling
docs(readme): update installation steps
```

**Common scopes:**

* `api` - API changes
* `ui` - User interface
* `cli` - Command-line interface
* `db` - Database
* `auth` - Authentication
* `docs` - Documentation
* `tests` - Testing

<Tip>
  Choose scopes that make sense for your project. Consistency is more important than having many scopes.
</Tip>

### Controlling scope display

Show or hide scopes in release notes:

```bash theme={}
# With scopes (default)
gitreleasegen generate --include-scopes
# Output: "**api**: Add authentication endpoint"

# Without scopes
gitreleasegen generate --no-include-scopes
# Output: "Add authentication endpoint"
```

## Breaking changes

Breaking changes can be indicated in two ways:

### Method 1: Exclamation mark

```bash theme={}
feat(api)!: change authentication flow

This changes the authentication from API keys to OAuth2.
```

### Method 2: BREAKING CHANGE footer

```bash theme={}
feat(api): change authentication flow

BREAKING CHANGE: API key authentication is removed.
All clients must migrate to OAuth2.
```

Both methods create a **Breaking Changes** section in release notes.

<Warning>
  Breaking changes appear prominently in release notes to alert users about incompatible changes.
</Warning>

## Examples by category

### Features

<CodeGroup>
  ```bash User-facing feature theme={}
  feat(ui): implement real-time notifications

  Added WebSocket support for live updates.
  Users see changes instantly without refreshing.
  ```

  ```bash API feature theme={}
  feat(api): add bulk user import endpoint

  New POST /api/users/bulk endpoint accepts CSV files.
  Supports up to 10,000 users per batch.
  ```

  ```bash Infrastructure feature theme={}
  feat(infra): add Redis caching layer

  Implements caching for frequently accessed data.
  Reduces database load by ~60%.
  ```
</CodeGroup>

### Bug fixes

<CodeGroup>
  ```bash Critical fix theme={}
  fix(security): patch SQL injection vulnerability

  Sanitized user input in search queries.
  All user-provided data now properly escaped.
  ```

  ```bash UI fix theme={}
  fix(ui): resolve mobile navigation menu

  Fixed hamburger menu not appearing on mobile devices.
  Tested on iOS and Android.
  ```

  ```bash Data fix theme={}
  fix(db): correct timezone handling

  Fixed inconsistent timestamp storage.
  All dates now stored in UTC.
  ```
</CodeGroup>

### Documentation

<CodeGroup>
  ```bash API documentation theme={}
  docs(api): add authentication examples

  Added code samples for all auth methods.
  Includes cURL, Python, and JavaScript examples.
  ```

  ```bash Guide updates theme={}
  docs(guide): improve troubleshooting section

  Added solutions for common installation errors.
  Reorganized content for better flow.
  ```
</CodeGroup>

### Refactoring

<CodeGroup>
  ```bash Code improvement theme={}
  refactor(parser): extract commit parsing logic

  Moved parsing to dedicated module.
  Improved testability and maintainability.
  ```

  ```bash Structure change theme={}
  refactor(api): reorganize endpoint handlers

  Grouped related endpoints into modules.
  Reduced file size and improved navigation.
  ```
</CodeGroup>

## Complete example workflow

Here's how Conventional Commits work in a real project:

<Steps>
  <Step title="Make changes and commit">
    ```bash theme={}
    # Feature commit
    git commit -m "feat(auth): add Google OAuth integration"

    # Bug fix commit
    git commit -m "fix(api): handle timeout errors gracefully"

    # Breaking change commit
    git commit -m "feat(api)!: migrate to GraphQL

    BREAKING CHANGE: REST endpoints removed.
    See migration guide at docs/migration-v2.md"
    ```
  </Step>

  <Step title="Generate release notes">
    ```bash theme={}
    gitreleasegen generate --unreleased --format markdown
    ```
  </Step>

  <Step title="Review organized output">
    ```markdown theme={}
    ## Release v2.0.0

    ### Breaking Changes
    - **api**: Migrate to GraphQL (abc123)
      REST endpoints removed. See migration guide.

    ### Features
    - **auth**: Add Google OAuth integration (def456)

    ### Bug Fixes
    - **api**: Handle timeout errors gracefully (ghi789)
    ```
  </Step>
</Steps>

<Check>
  Commits are automatically organized into sections based on their type.
</Check>

## Best practices

<AccordionGroup>
  <Accordion title="Use descriptive commit messages">
    **Good:**

    ```bash theme={}
    feat(auth): add two-factor authentication

    Implements TOTP-based 2FA with QR code generation.
    Supports authenticator apps like Google Authenticator.
    ```

    **Avoid:**

    ```bash theme={}
    feat: add stuff
    feat: updates
    fix: bug fix
    ```
  </Accordion>

  <Accordion title="Be consistent with scopes">
    Define scopes for your project and use them consistently:

    ```bash theme={}
    # Good - consistent scopes
    feat(api): add endpoint
    feat(ui): add component
    feat(db): add migration

    # Avoid - inconsistent scopes
    feat(api): add endpoint
    feat(frontend): add component
    feat(database-layer): add migration
    ```
  </Accordion>

  <Accordion title="Include context in commit body">
    ```bash theme={}
    feat(search): implement full-text search

    Added PostgreSQL full-text search for user queries.

    - Indexed title and description fields
    - Supports phrase matching with quotes
    - Average query time: <50ms
    - Handles 1M+ records efficiently
    ```
  </Accordion>

  <Accordion title="Reference issues and PRs">
    ```bash theme={}
    fix(api): resolve rate limiting bug (#123)

    Fixed calculation error in token bucket algorithm.

    Closes #122
    Related to #115
    ```
  </Accordion>

  <Accordion title="Use breaking changes sparingly">
    Only mark commits as breaking when they truly require user action:

    ```bash theme={}
    # Breaking - requires migration
    feat(api)!: change response format to camelCase

    BREAKING CHANGE: All API responses now use camelCase.
    Update your client code accordingly.

    # Not breaking - backward compatible
    feat(api): add new optional parameter

    Added optional 'filter' parameter to /api/users.
    Existing clients continue to work without changes.
    ```
  </Accordion>
</AccordionGroup>

## Converting existing commits

If your project doesn't use Conventional Commits:

### Option 1: Start today

Begin using Conventional Commits for new commits while keeping existing history as-is:

```bash theme={}
# From now on, use Conventional Commits
git commit -m "feat(api): add new endpoint"
```

### Option 2: Rewrite history (use with caution)

For personal projects or before pushing:

```bash theme={}
# Interactive rebase to edit messages
git rebase -i HEAD~10

# In the editor, mark commits to reword:
# reword abc123 Old commit message
# reword def456 Another old message

# Update each commit to Conventional Commits format
```

<Warning>
  Never rewrite history on shared branches. Only do this for private work.
</Warning>

### Option 3: Manual categorization

GitReleaseGen does its best to categorize non-conventional commits, but results may vary.

## Integration with GitReleaseGen

### Automatic categorization

```bash theme={}
# These commits:
feat(ui): add dashboard
fix(api): resolve bug
docs: update readme
chore: bump dependencies

# Become this output:
```

```markdown theme={}
## Release

### Features
- **ui**: Add dashboard

### Bug Fixes
- **api**: Resolve bug

### Documentation
- Update readme

### Chores
- Bump dependencies
```

### Breaking change detection

```bash theme={}
# This commit:
feat(api)!: change authentication

BREAKING CHANGE: API keys no longer supported.
Use OAuth2 instead.

# Creates this section:
```

```markdown theme={}
### Breaking Changes
- **api**: Change authentication (abc123)
  API keys no longer supported. Use OAuth2 instead.
```

## Tools and resources

<CardGroup cols={2}>
  <Card title="Conventional Commits spec" icon="file-lines" href="https://www.conventionalcommits.org/">
    Official specification and guidelines
  </Card>

  <Card title="Commitlint" icon="check" href="https://commitlint.js.org/">
    Lint commit messages in CI/CD
  </Card>

  <Card title="Commitizen" icon="terminal" href="https://commitizen-tools.github.io/commitizen/">
    Interactive commit message helper
  </Card>

  <Card title="Git hooks" icon="git" href="https://git-scm.com/docs/githooks">
    Enforce format with pre-commit hooks
  </Card>
</CardGroup>

## Commitlint integration

Enforce Conventional Commits in your project:

```bash theme={}
# Install commitlint
npm install --save-dev @commitlint/{config-conventional,cli}

# Configure
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Add hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
```

Now commits must follow Conventional Commits format:

```bash theme={}
git commit -m "feat: add feature"  # ✓ Passes
git commit -m "add feature"        # ✗ Fails
```

## Next steps

<CardGroup cols={2}>
  <Card title="Examples" icon="code" href="/examples" color="#0A6ACB">
    See Conventional Commits in action
  </Card>

  <Card title="CLI reference" icon="terminal" href="/cli-reference" color="#F26419">
    Learn about scope display options
  </Card>

  <Card title="GitHub integration" icon="github" href="/github-integration" color="#0A6ACB">
    Link commits to pull requests
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration" color="#F6A02D">
    Customize commit processing
  </Card>
</CardGroup>