Enterprise Git Commit Workflow

This skill enforces Conventional Commits specification for enterprise projects, ensuring consistent, readable, and automatable commit messages.

Format

<type>[optional scope][!]: <description>

Required: Type and description Optional: Scope, breaking change indicator (!)

Commit Types

Type	Purpose
feat	New feature
fix	Bug fix
docs	Documentation only
style	Code style (formatting, no logic change)
refactor	Code restructuring (no behavior change)
perf	Performance improvement
test	Adding/updating tests
build	Build system/dependencies
ci	CI/CD configuration
chore	Other maintenance tasks
revert	Revert a commit

For detailed type decision guidance, see commit-types.md.

Writing Style Rules

• Imperative mood: Use "add" not "added" or "adds"
• Lowercase first letter: "add feature" not "Add feature"
• No trailing period: "add feature" not "add feature."
• Subject max 72 chars: Total length including type/scope
• Body wrap at 72: If adding a detailed body

Examples:

• ✅ feat(api): add user authentication
• ✅ fix(auth): resolve token expiration
• ❌ feat(api): Add user authentication.
• ❌ Updated the authentication flow

Workflow

1. Full Commit Workflow

When user requests creating a commit:

1. Analyze changes

   git status
   git diff --staged
   git log -5 --oneline
   

2. Determine commit type - Use the decision tree in commit-types.md

3. Determine scope (optional) - Based on affected area (api, ui, auth, database, etc.)

4. Check for breaking changes - Does this break existing functionality?

5. Draft commit message following the format:

   • Start with type and scope
   • Add ! if breaking
   • Add colon and space
   • Write description in imperative mood

6. Stage files (if not already staged):

   git add <files>
   

7. Validate commit message using the validation script (see below)

8. Create commit:

   git commit -m "$(cat <<'EOF'
   <type>[scope]: <description>
   
   [optional body]
   
   [optional footer]
   EOF
   )"
   

9. Run git status to verify success

2. Validate Commit Message

Use the validation script to check commit message format:

echo "feat(api): add user endpoint" | python3 scripts/validate_commit.py

The script checks:

• Valid commit type
• Proper format (type: description or type(scope): description)
• Description not empty
• Imperative mood (lowercase start)
• No trailing period
• Subject under 72 characters

Exit code: 0 for valid, 1 for invalid.

3. Generate Commit Message from Changes

To generate a commit message based on code changes:

1. Analyze the diff: git diff --staged
2. Identify the primary change type
3. Determine affected scope
4. Draft a concise description
5. Validate the message

Analysis prompts:

• Multiple related changes → Group under single cohesive message
• Mixed types → Split into multiple logical commits
• Complex changes → Add body paragraph explaining context

Breaking Changes

For breaking changes, add ! after type/scope:

feat(api)!: remove deprecated endpoint

BREAKING CHANGE: The /users endpoint has been removed.
Use /v2/users instead.

Commit Message with Body

For complex changes, add a body:

feat(api): add user pagination

Implement cursor-based pagination for improved performance
with large datasets.

- Add before/after cursor parameters
- Limit max results to 100 per page
- Include pagination metadata in response

Closes #123

Common Patterns

Fix a bug

fix(auth): resolve session timeout issue

Add a feature

feat(api): add user search functionality

Update dependencies

chore(deps): upgrade react to v18

Refactor code

refactor(auth): extract token validation

Breaking change

feat(api)!: change authentication format

BREAKING CHANGE: API now requires Bearer token format.
Update all API clients accordingly.

Reference

• Full specification: conventional-commits.md
• Type decision guide: commit-types.md
• Validation script: scripts/validate_commit.py