conventional-commits by avvale/aurora-front

When to Use

User asks to create a commit or "commit changes"
User asks to review git status or diff
User wants to analyze commit history
After completing features/fixes that need to be committed
User mentions "conventional commits" or asks about commit format

Critical Patterns

Commit Format

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

[optional body]

[optional footer]

Types (in order of usage frequency)

Type	Description	Example
`feat`	New functionality	`feat(library/book): add ISBN validation`
`fix`	Bug fix	`fix(auth): resolve token refresh race condition`
`refactor`	Code refactoring, no functional change	`refactor(core): extract validation logic to service`
`test`	Add or modify tests	`test(book): add unit tests for create handler`
`docs`	Documentation changes	`docs(readme): add installation instructions`
`chore`	Maintenance tasks	`chore(deps): update nestjs to v10`
`style`	Formatting, semicolons, etc.	`style(api): apply prettier formatting`
`perf`	Performance improvements	`perf(query): optimize book search with index`
`ci`	CI/CD changes	`ci(github): add deployment workflow`
`build`	Build system or dependencies	`build(docker): optimize production image`
`revert`	Revert previous commit	`revert: feat(book): add ISBN validation`

Subject Rules

✅ Use imperative mood: "add" NOT "added" or "adds"
✅ Lowercase first letter
✅ No period at the end
✅ Maximum 120 characters
✅ Describe WHAT, not HOW

Good:

feat(book): add publication date validation
fix(auth): resolve token refresh issue

Bad:

feat(book): Added publication date validation (past tense)
fix(auth): Resolve token refresh issue (uppercase)
feat(book): add publication date validation. (period)

Body Rules (Optional)

Separate from subject with blank line
Explain WHY, not WHAT
Wrap at 72 characters per line
Can use bullet points with -

Footer Rules (Optional)

Reference issues: Closes #123, Fixes #456
Breaking changes: BREAKING CHANGE: <description>
❌ NEVER add "Co-Authored-By" or AI attribution

Commit Workflow

1. Analyze Changes

git status                # See modified/untracked files
git diff                  # See unstaged changes
git diff --staged         # See staged changes
git log --oneline -10     # See recent commit style

2. Group Related Changes

Rules:

One commit = one logical change
❌ Don't mix features with fixes
❌ Don't mix multiple unrelated modules
✅ Multiple files are OK if they implement one feature

3. Generate Message

Analyze the changes and determine:

Type: feat, fix, refactor, etc.
Scope: Which module/component is affected?
Subject: What does this change do?
Body (if needed): Why was this change necessary?
Footer (if needed): Issue references, breaking changes

4. Execute Commit

git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body>

<footer>
EOF
)"

Code Examples

Simple Feature

feat(library/book): add publication date validation

Validate that publication date is not in the future
when creating or updating a book.

Closes #234

Bug Fix with Context

fix(auth): resolve token refresh race condition

Multiple simultaneous requests could trigger parallel
token refreshes, causing some requests to fail.

- Add mutex lock during refresh
- Queue pending requests until refresh completes
- Add retry logic for failed requests

Fixes #567

Refactor (No Functional Change)

refactor(library/book): extract ISBN validation to service

Move ISBN validation logic from command handler to
dedicated IsbnValidatorService for reusability.

No functional changes.

Breaking Change

feat(api)!: change pagination response format

BREAKING CHANGE: Pagination response now uses cursor-based
format instead of offset-based.

Before: { items: [], total: 100, page: 1 }
After: { items: [], nextCursor: "abc", hasMore: true }

Migration guide in docs/migration/v2-pagination.md

Aurora YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with:
- id, name, description fields
- many-to-many relation with Book

Run: aurora load back module -n=library/category

Dependency Update

chore(deps): update @nestjs packages to v10.2.0

- @nestjs/core: 10.1.0 -> 10.2.0
- @nestjs/common: 10.1.0 -> 10.2.0
- @nestjs/platform-express: 10.1.0 -> 10.2.0

No breaking changes in this update.

Multiple Modules (Related Change)

feat(tesla): add maintenance validation across models

- Add validation in Model aggregate
- Update MaintenanceHistory to check model status
- Add integration tests for both modules

This ensures consistency when creating maintenance records.

Commands

# View status
git status

# View changes
git diff                    # Unstaged changes
git diff --staged          # Staged changes
git diff --cached          # Same as --staged

# Stage files
git add <file>             # Stage specific file
git add -p                 # Interactive staging (choose hunks)

# Commit
git commit -m "message"    # Simple commit
git commit                 # Opens editor for body

# View history
git log --oneline -20                      # Last 20 commits
git log --pretty=format:"%h %s" -20       # Custom format
git log --graph --oneline --all           # Visual graph

# Amend last commit (use with caution)
git commit --amend -m "new message"       # Change message
git commit --amend --no-edit              # Add files to last commit

Anti-Patterns to Avoid

❌ Bad	✅ Good
`git commit -m "fix"`	`fix(auth): resolve token expiration bug`
`git commit -m "WIP"`	Finish the work or use feature branch
`git commit -m "changes"`	`refactor(core): extract common validation logic`
`git commit -m "update files"`	`feat(book): add ISBN field to entity`
`git commit -am "everything"`	Split into logical commits
Mix feat + fix + refactor	Separate commits for each type
Commit generated files only	Commit YAML changes + explain regeneration

Aurora-Specific Notes

1. YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with id, name, description.

Run: aurora load back module -n=library/category

2. Custom Logic in Generated Files

feat(library/book): add complex ISBN validation logic

Implement custom validation in CreateBookHandler:
- Validate ISBN format (10 or 13 digits)
- Check checksum digit
- Verify not in blacklist

This logic is in a generated file marked as custom.

3. Multiple Related Modules

feat(tesla): integrate maintenance history with models

- Update Model aggregate with maintenance status
- Add validation in MaintenanceHistory creation
- Add integration tests

Changes span tesla/model and tesla/maintenance-history.

4. Test Commits

Option A: Combined with feature

feat(book): add ISBN validation with tests

- Add ISBN validation in CreateBookHandler
- Add unit tests for validation logic
- Add e2e tests for create endpoint

Option B: Separate commit

test(book): add unit tests for ISBN validation

Add comprehensive test coverage for:
- Valid ISBN-10 and ISBN-13 formats
- Invalid formats and checksums
- Edge cases (empty, null, special chars)

Decision Trees

Should I commit now?

Has code changed? ────NO───> No commit needed
      │
     YES
      │
Is it a logical unit? ────NO───> Break into smaller commits
      │
     YES
      │
Do tests pass? ────NO───> Fix tests first
      │
     YES
      │
  Create commit

What type should I use?

New functionality? ────YES───> feat
      │
      NO
      │
Fixing a bug? ────YES───> fix
      │
      NO
      │
No functional change? ────YES───> refactor
      │
      NO
      │
Only tests? ────YES───> test
      │
      NO
      │
Dependencies? ────YES───> chore(deps)
      │
      NO
      │
Documentation? ────YES───> docs
      │
      NO
      │
    Default: chore

How to scope?

Single module changed? ────YES───> Use <bc>/<module>
      │
      NO
      │
Multiple related modules? ────YES───> Use common <bc> or higher scope
      │
      NO
      │
Infrastructure? ────YES───> Use: ci, docker, config, deps
      │
      NO
      │
Core/API/GraphQL? ────YES───> Use: core, api, graphql
      │
      NO
      │
    Omit scope or use project name

Related Skills

This skill works with:

aurora-cli: Commit YAML changes and regenerated code
aurora-development: Commit business logic implementations (feat commits)
jest-nestjs: Commit test files (test commits or include with feat)
logger: Log commit information in session reports

Workflow:

Make changes (YAML modifications, business logic, tests)
Use aurora-cli to regenerate code (if YAML changed)
Use conventional-commits to create proper commit
Use logger to document the session (optional)

Resources

Specification: https://www.conventionalcommits.org/
Aurora Config: commitlint.config.js (read this for project-specific rules)
Git Hooks: Pre-commit hooks may enforce format validation