commit-helper

davjdk 的头像作者 davjdk

Manage git commit workflow with size limits and conventional commits. Use before any commit. Enforces max_commit_change_lines policy. NOTE: CHANGELOG is updated only during merge, not during individual commits.

📖 中文导读:Manage git commit workflow with size limits and conventional commits. Use before any commit. Enforces max_commit_change_lines policy. NOTE: CHANGELOG is updated only during merge, not during individual commits. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: commit-helper description: Manage git commit workflow with size limits and conventional commits. Use before any commit. Enforces max_commit_change_lines policy. NOTE: CHANGELOG is updated only during merge, not during individual commits.

Commit Helper Skill

You guide the git commit process ensuring quality and consistency.

IMPORTANT: CHANGELOG.md is NOT updated during individual commits. It is updated ONLY once during merge to main branch by merge-helper.

When to Use This Skill

  • User asks to commit changes
  • Before creating any commit
  • When preparing to merge branches
  • When changes need to be split into multiple commits

Configuration

Read from .ai/ai-settings.json:

{
  "framework": {
    "specs": {
      "max_commit_change_lines": 250
    }
  }
}

Pre-Commit Checklist

Step 1: Check Commit Size

git diff --stat

Calculate total changes: Added + Modified lines (excluding deletions)

If > 250 lines:

Commit Size Exceeds Limit

Current changes: ~450 lines
Limit: 250 lines

Action Required: Split into multiple commits

Suggested breakdown:
1. Commit 1: Core functionality (~200 lines)
   - Files: file1.py, file2.py
2. Commit 2: Tests (~150 lines)
   - Files: test_file.py
3. Commit 3: Documentation (~100 lines)
   - Files: README.md, docs/api.md

Shall I help you split these changes?

Exclusions (not counted toward limit):

  • *.lock files (uv.lock, poetry.lock)
  • alembic/versions/*.py (database migrations)
  • *.generated.* files (auto-generated)
  • .ai/*.md (framework documentation)

Step 2: Verify Tests Pass

uv run pytest

If tests fail:

Tests Failing

Tests: 5 failed, 42 passed

Action Required: Fix failing tests before committing

Do not commit with failing tests. Fix the issues first.

Step 3: Generate Commit Message

Follow project conventions:

Types:

  • feat: - New functionality
  • fix: - Bug fix
  • refactor: - Code restructuring
  • test: - Test additions/changes
  • docs: - Documentation
  • chore: - Maintenance tasks

Format:

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

[Optional detailed body]

[Optional footer]

Examples:

feat(thermocalc): add chart service for matplotlib integration

- ChartService class for generating reaction/compound charts
- Base64 encoding for HTML embedding
- Support for ΔG, ΔH, ΔS, K, Cp, G, H, S charts

Closes #123
fix(auth): correct JWT token validation for expired tokens

- Added proper expiration check
- Return 401 instead of 500 on expired token
refactor(scheduler): extract email logic to infrastructure layer

- Moved EmailService to infrastructure/email/
- Updated scheduler to use generic email commands

Commit Creation Workflow

Workflow for Single Commit (< 250 lines)

  1. Pre-commit checks:

    git diff --stat
    uv run pytest
    
  2. Stage files:

    git add file1.py file2.py
    
  3. Create commit:

    git commit -m "type(scope): description"
    
  4. Verify:

    git log -1 --stat
    

Workflow for Large Changes (> 250 lines)

  1. Analyze changes:

    git diff --stat
    
  2. Plan atomic commits:

    • Group related files
    • Ensure logical completeness
    • Order by dependency
  3. Execute commits in sequence:

    # Commit 1
    git add <files-for-commit-1>
    git commit -m "type(scope): part 1"
    
    # Commit 2
    git add <files-for-commit-2>
    git commit -m "type(scope): part 2"
    
    # ... continue until all changes committed
    

Pre-Merge Checklist

Before merging to master/main:

  1. Verify environment:

    cat .env
    # Should be production settings, not development
    
  2. Check .env status:

    git status
    # .env should NOT be in staged
    
  3. Restore production config (if needed):

    copy .env.production .env
    
  4. Final verification:

    git diff master --stat
    uv run pytest
    

Output Format

Successful Commit

Commit Created Successfully

Type: feat
Scope: thermocalc
Message: add chart service for matplotlib integration

Files changed: 3
Lines added: 145
Lines deleted: 12

Commit hash: a1b2c3d

Pre-Merge Validation

Pre-Merge Validation Passed

Branch: feature/thermocalc-integration
Base branch: master
Commits to merge: 4

Environment: production (.env = .env.production)
Tests: All passing (47 passed)

Ready to merge. Use merge-helper for CHANGELOG update and merge.

Error Conditions

Tests Failing

Cannot Commit: Tests Failing

Run: uv run pytest
Fix: Address failing tests first

.env Would Be Committed

Cannot Commit: .env in Staged

Issue: .env contains development secrets
Fix: Remove .env from git add

Commit Too Large

Commit Exceeds Size Limit

Current: 450 lines
Limit: 250 lines

Action: Split into multiple atomic commits

References

See commit_logic.md for advanced git workflows. See validators.md for pre-commit validation rules. See merge-helper for CHANGELOG update during merge.

NOTE: CHANGELOG is updated ONCE during merge to main by merge-helper, not during individual commits.