Git Commit and Push Guidelines for AI Assistants

This skill defines the standards for creating Git commits when code changes are generated by AI assistants.

Commit Message Format

AI-generated commits MUST follow the Conventional Commits specification with detailed explanations and proper attribution.

Structure

<type>(<scope>): <summary>

<blank line>
<detailed body explaining the changes>

<blank line>
<test coverage information>

<blank line>
Co-authored-by: GitHub Copilot using <model name>

Components

1. Header Line: <type>(<scope>): <summary>

Format: <type>(<scope>): <summary>

• type: The kind of change (see Types section below)
• scope: The module/component affected (e.g., meter, watcher, reporter)
• summary: Brief description in imperative mood (50 chars max)

Example:

feat(meter): implement idempotent termination behavior

2. Detailed Body

After a blank line, provide a comprehensive explanation:

First Paragraph: High-level description of what changed and why

Meter termination methods (ok, reject, fail) now properly handle repeated
termination attempts by preserving the first termination state.

Changes Section: Bulleted list of technical changes

Changes:
- MeterValidator.validateStopPrecondition() now returns boolean instead of void
  - Returns false when meter already stopped (blocks re-termination)
  - Returns true otherwise (allows termination with warnings)
- Meter.commonOk(), reject(), fail() methods now check validation result
  - Early return when meter already stopped, preserving first termination
- Updated 86 test cases to verify idempotent behavior
  - MeterValidatorTest: 4 tests updated to capture boolean return
  - MeterLogBugTest: 6 tests updated for exception handling
  - MeterLifeCyclePreStartTerminatedPostStopInvalidTerminationTest: 28 tests
    updated to verify first termination wins

Guidelines for Changes Section:

• Use bullet points with - for main items
• Indent sub-bullets with 2 spaces
• Group related changes together
• Include quantitative information (e.g., "86 test cases", "4 tests updated")
• Mention specific class/method names for traceability

3. Test Coverage Information

After changes, include test validation results:

All 1710 Meter tests pass, confirming backward compatibility.

Guidelines:

• State total number of tests executed
• Confirm backward compatibility if applicable
• Mention any new test coverage added

4. AI Attribution

REQUIRED: Every AI-generated commit must include proper attribution:

Co-authored-by: GitHub Copilot using <model name>

Where <model name> is the specific AI model used (e.g., Claude Sonnet 4.5, GPT-4, Claude Haiku 4.5).

Why: This provides transparency about AI assistance and maintains proper attribution standards.

Commit Types

Use standard Conventional Commits types:

Type	Description	When to Use
feat	New feature	Adding new functionality, capabilities, or APIs
fix	Bug fix	Fixing a defect or incorrect behavior
refactor	Code refactoring	Restructuring code without changing behavior
perf	Performance improvement	Optimizing performance or resource usage
test	Test changes	Adding/updating tests (no production code changes)
docs	Documentation	Adding/updating documentation, comments, or README
style	Code style	Formatting, whitespace, code style (no logic changes)
chore	Maintenance	Build scripts, dependencies, tooling configuration
ci	CI/CD changes	GitHub Actions, build pipelines, automation
revert	Revert previous commit	Undoing a previous change

Scope Guidelines

Common scopes in slf4j-toys project:

• meter - Meter class and related utilities
• watcher - Watcher functionality
• reporter - Reporter and diagnostic features
• logger - LoggerFactory utilities
• test - Test infrastructure and utilities
• build - Build configuration and Maven
• ci - CI/CD workflows

Complete Example

git commit -m "feat(meter): implement idempotent termination behavior

Meter termination methods (ok, reject, fail) now properly handle repeated
termination attempts by preserving the first termination state.

Changes:
- MeterValidator.validateStopPrecondition() now returns boolean instead of void
  - Returns false when meter already stopped (blocks re-termination)
  - Returns true otherwise (allows termination with warnings)
- Meter.commonOk(), reject(), fail() methods now check validation result
  - Early return when meter already stopped, preserving first termination
- Updated 86 test cases to verify idempotent behavior
  - MeterValidatorTest: 4 tests updated to capture boolean return
  - MeterLogBugTest: 6 tests updated for exception handling
  - MeterLifeCyclePreStartTerminatedPostStopInvalidTerminationTest: 28 tests
    updated to verify first termination wins

All 1710 Meter tests pass, confirming backward compatibility.

Co-authored-by: GitHub Copilot using Claude Sonnet 4.5"

Git Commands Workflow

1. Stage Files

# Stage specific files
git add path/to/file1.java path/to/file2.java

# Or stage all modified files
git add -u

2. Create Commit

# Use multi-line commit message
git commit -m "type(scope): summary

Detailed body...

Co-authored-by: GitHub Copilot using <model>"

3. Push Changes

# Push to current branch
git push

# Push to specific remote and branch
git push origin branch-name

Best Practices

DO:

• ✅ Always include Co-authored-by attribution for AI-generated code
• ✅ Provide comprehensive change descriptions
• ✅ Include test coverage information
• ✅ Use imperative mood in summary ("implement", not "implemented")
• ✅ Keep summary line under 50 characters
• ✅ Wrap body text at 72 characters
• ✅ Separate concerns into multiple commits when appropriate
• ✅ Reference issue numbers if applicable (e.g., "Fixes #123")

DON'T:

• ❌ Mix unrelated changes in a single commit
• ❌ Create commits without proper attribution
• ❌ Use vague descriptions like "fix stuff" or "update code"
• ❌ Skip test validation information
• ❌ Forget to run tests before committing
• ❌ Force push to protected branches (main)

PowerShell-Specific Considerations

When creating multi-line commit messages in PowerShell, you may need to handle line breaks carefully:

Option 1: Use backticks for line continuation:

git commit -m "feat(scope): summary`n`nBody text`n`nCo-authored-by: GitHub Copilot using Claude Sonnet 4.5"

Option 2: Use here-strings:

$commitMessage = @"
feat(scope): summary

Body text

Co-authored-by: GitHub Copilot using Claude Sonnet 4.5
"@
git commit -m $commitMessage

Option 3: Interactive commit editor:

# Opens default editor for commit message
git commit

Verification

After committing, verify the commit message format:

# View last commit message
git log -1 --pretty=format:"%B"

# View last commit with stats
git show --stat

Related Documentation

• Conventional Commits Specification
• AGENTS.md - Project AI agent guidelines
• .github/copilot-instructions.md - AI attribution standards