Git Commit Push Useful Toys

---
name: git-commit-push
description: 'Guidelines for creating AI-generated Git commits with proper format and attribution'
---

# 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](https://www.conventionalcommits.org/) 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

```bash
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

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

# Or stage all modified files
git add -u
```

### 2. Create Commit

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

Detailed body...

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

### 3. Push Changes

```powershell
# 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:
```powershell
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:
```powershell
$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:
```powershell
# Opens default editor for commit message
git commit
```

## Verification

After committing, verify the commit message format:

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

# View last commit with stats
git show --stat
```

## Related Documentation

- [Conventional Commits Specification](https://www.conventionalcommits.org/)
- [AGENTS.md](../../../AGENTS.md) - Project AI agent guidelines
- [.github/copilot-instructions.md](../../copilot-instructions.md) - AI attribution standards