Conventional Commit Message Creation
Create properly formatted conventional commit messages following project standards with Jira integration, line length validation, and required footers.
Purpose
Generate commit messages that:
- Follow conventional commits format (
type(scope): description) - Integrate Jira issue numbers automatically
- Respect line length limits (50 for subject, 72 for body)
- Include required footers (Signed-off-by, Assisted-by)
- Pass gitlint validation
Quick Workflow
- Analyze changes: Run git status and git diff to understand modifications
- Detect Jira scope: Extract issue number from branch name or ask user
- Generate message: Create conventional commit message with proper formatting
- Add footers: Include Signed-off-by and Assisted-by trailers
- Confirm with user: Display message and wait for approval before committing
CRITICAL: Never commit without explicit user confirmation.
Conventional Commit Format
Structure
<type>(<scope>): <description>
[optional body]
Signed-off-by: <name> <email>
Assisted-by: <model-name> (via Claude Code)
```text
### Type Selection
Choose the appropriate commit type based on changes:
| Type | Description | Example |
| ------ | ------------- | --------- |
| `feat` | New features | `feat(webhook): add GitHub App support` |
| `fix` | Bug fixes | `fix(controller): resolve pipeline race condition` |
| `docs` | Documentation | `docs(README): update installation steps` |
| `refactor` | Code refactoring | `refactor(matcher): simplify regex logic` |
| `test` | Test changes | `test(webhook): add integration tests` |
| `chore` | Maintenance | `chore(deps): update go dependencies` |
| `build` | Build system | `build(Makefile): add vendor target` |
| `ci` | CI/CD changes | `ci(github): add golangci-lint action` |
| `perf` | Performance | `perf(cache): optimize lookup speed` |
| `style` | Code style | `style(format): run fumpt formatter` |
| `revert` | Revert commit | `revert: undo breaking API change` |
For complete type reference, see `references/commit-types.md`.
### Scope Rules
#### Priority 1: Extract from branch name
```bash
# Branch: SRVKP-123-add-webhook-support
# Scope: SRVKP-123
# Result: feat(SRVKP-123): add webhook support
```text
Detect Jira issue using regex pattern: `[A-Z]{2,}-[0-9]+`
#### Priority 2: Ask user for Jira issue
If branch is `main`, `master`, or doesn't contain Jira pattern:
1. Ask user for Jira issue number
2. Look up issue on issues.redhat.com if provided
3. Use component name as fallback (webhook, controller, etc.)
#### Priority 3: Component fallback
Use affected component as scope:
- `feat(webhook): ...`
- `fix(controller): ...`
- `docs(README): ...`
## Line Length Requirements
### Subject Line
- **Target**: 50 characters maximum
- **Hard limit**: 72 characters (gitlint enforced)
- **Format**: `type(scope): description` counts toward limit
- **Tips**: Use present tense, no period at end
```text
# Good (45 chars)
feat(SRVKP-123): add webhook controller
# Too long (78 chars) - will fail gitlint
feat(SRVKP-123): add comprehensive webhook controller with GitHub integration
```text
### Body
- **Wrap at 72 characters per line**
- **Blank line** required between subject and body
- **Content**: Explain why, not what (code shows what)
- **Format**: Wrap manually or use heredoc in git commit
```text
feat(SRVKP-123): add webhook controller
Configure webhook controller to handle GitHub events. This enables
real-time pipeline triggering when push events occur, replacing the
previous polling mechanism.
Signed-off-by: Developer Name <[email protected]>
Assisted-by: Claude-3.5-Sonnet (via Claude Code)
```text
## Required Footers
### Signed-off-by
**Always include**: `Signed-off-by: <name> <email>`
**Detection priority order**:
1. Environment variables: `$GIT_AUTHOR_NAME` and `$GIT_AUTHOR_EMAIL`
2. Git config: `git config user.name` and `git config user.email`
3. If neither configured, ask user to provide details
**Common in dev containers**: Environment variables are preferred method
```bash
# Check environment variables first
echo "$GIT_AUTHOR_NAME <$GIT_AUTHOR_EMAIL>"
# Fallback to git config
git config user.name
git config user.email
```text
For complete detection logic, see `references/footer-detection.md`.
### Assisted-by
**Always include**: `Assisted-by: <model-name> (via Claude Code)`
**Format examples**:
```text
Assisted-by: Claude-3.5-Sonnet (via Claude Code)
Assisted-by: Claude Opus 4.5 (via Claude Code)
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
```text
Use the actual model name (Claude Sonnet 4.5, Claude Opus 4.5, etc.).
## User Confirmation Requirement
**CRITICAL RULE**: Always ask for user confirmation before executing `git commit`.
### Confirmation Workflow
1. **Generate** the commit message following all rules above
2. **Display** the complete message to the user with separator
3. **Ask**: "Should I commit with this message? (y/n)"
4. **Wait** for user response
5. **Commit** only if user confirms (yes/y/affirmative)
### Example Interaction
```text
Generated commit message:
---
feat(SRVKP-456): ensure webhook logs output to stdout
Configure webhook controller to direct all logs to stdout for
container compatibility. This resolves logging issues in Kubernetes
environments where logs are collected from stdout.
Signed-off-by: Developer Name <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
---
Should I commit with this message? (y/n)
```text
Wait for user response before proceeding.
## Commit Execution
Use heredoc format for proper multi-line handling:
```bash
git commit -m "$(cat <<'EOF'
feat(SRVKP-456): ensure webhook logs output to stdout
Configure webhook controller to direct all logs to stdout for
container compatibility.
Signed-off-by: Developer Name <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
EOF
)"
```text
**Never use**:
- `--no-verify` (skips pre-commit hooks)
- `--no-gpg-sign` (skips signing)
- `--amend` (unless explicitly requested and safe)
## Complete Examples
### Feature with Jira Scope
```text
feat(SRVKP-789): add GitLab webhook integration
Implement webhook handler for GitLab push events. This enables
pipeline triggering from GitLab repositories using the same
architecture as GitHub integration.
Signed-off-by: Jane Developer <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
```text
### Bug Fix with Component Scope
```text
fix(controller): resolve concurrent pipeline runs
Update pipeline reconciliation logic to handle concurrent runs
correctly. Previously, race condition could cause pipeline state
corruption when multiple runs started simultaneously.
Signed-off-by: John Developer <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
```text
### Documentation Update
```text
docs(README): update installation steps
Add section about pre-commit hooks and update Go version
requirement to 1.20.
Signed-off-by: Jane Developer <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
```text
### Breaking Change
```text
feat(api)!: change webhook payload format
Update webhook payload to use standardized event schema. This is a
breaking change requiring webhook consumers to update their
parsers.
BREAKING CHANGE: Webhook payload structure changed from nested
format to flat event schema. See migration guide in docs/.
Signed-off-by: John Developer <[email protected]>
Assisted-by: Claude Sonnet 4.5 (via Claude Code)
```text
## Jira Issue Lookup
When no Jira issue is found in branch name:
1. Ask user: "What Jira issue number should I use for this commit?"
2. If provided, search issues.redhat.com for issue details
3. Use issue summary and description to enhance commit message
4. Suggest creating a new branch with Jira issue in name if desired
For complete Jira lookup workflow, see `references/jira-lookup.md`.
## Gitlint Integration
This project uses gitlint to enforce commit message format. Ensure all commit messages pass gitlint validation.
**Common gitlint rules**:
- Conventional commit format required
- Subject line length limits (50 soft, 72 hard)
- Required footers (Signed-off-by)
- No trailing whitespace
- Body line wrapping at 72 characters
For complete gitlint rules, see `references/gitlint-rules.md`.
## Auto-Detection Summary
When generating commit messages:
1. Run `git status` (without -uall flag)
2. Run `git diff` for staged and unstaged changes
3. Check current branch name for Jira issue pattern `[A-Z]{2,}-[0-9]+`
4. If no Jira issue in branch, ask user for issue number
5. Look up issue details on issues.redhat.com if provided
6. Analyze staged files to determine commit type
7. Generate appropriate scope and description
8. Detect author info from environment variables or git config
9. Ensure subject line is ≤50 characters (max 72)
10. Wrap body text at 72 characters per line
11. Add required footers (Signed-off-by and Assisted-by)
12. Format according to conventional commits standard
13. **Display message and ask for user confirmation**
14. Only commit after receiving confirmation
## Additional Resources
For detailed information:
- **`references/commit-types.md`** - Complete commit type reference with descriptions
- **`references/jira-lookup.md`** - Jira issue lookup workflow and integration
- **`references/gitlint-rules.md`** - Gitlint validation rules and configuration
- **`references/footer-detection.md`** - Author detection logic and priority order