zhongwei/gh-dhofheinz-open-plugins-plugins-git-commit-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d6226e0d80cd717ae74dc79acd6de226d41e987
gh-dhofheinz-open-plugins-p…/commands/message-generation/add-footer.md
Zhongwei Li 0d6226e0d8 Initial commit
2025-11-29 18:20:25 +08:00

8.1 KiB
Raw Blame History

description
description
Add footer with breaking changes and issue references to commit message

Operation: Add Footer

Add a properly formatted footer to commit message with breaking changes, issue references, and other metadata.

Parameters from $ARGUMENTS

Optional (at least one required):

  • breaking: - Breaking change description
  • closes: - Comma-separated issue numbers to close
  • fixes: - Comma-separated issue numbers to fix
  • refs: - Comma-separated issue numbers to reference
  • reviewed: - Reviewer name(s)
  • signed: - Signed-off-by name and email

Format: footer breaking:"API changed" closes:123,456

Workflow

Step 1: Parse Parameters

Extract parameters from $ARGUMENTS:

# Parse footer components
breaking=$(echo "$ARGUMENTS" | grep -oP 'breaking:"\K[^"]+')
closes=$(echo "$ARGUMENTS" | grep -oP 'closes:\K[0-9,]+')
fixes=$(echo "$ARGUMENTS" | grep -oP 'fixes:\K[0-9,]+')
refs=$(echo "$ARGUMENTS" | grep -oP 'refs:\K[0-9,]+')
reviewed=$(echo "$ARGUMENTS" | grep -oP 'reviewed:"\K[^"]+')
signed=$(echo "$ARGUMENTS" | grep -oP 'signed:"\K[^"]+')

Step 2: Validate Parameters

Check at least one parameter provided:

if [ -z "$breaking" ] && [ -z "$closes" ] && [ -z "$fixes" ] && [ -z "$refs" ] && [ -z "$reviewed" ] && [ -z "$signed" ]; then
  echo "ERROR: At least one footer parameter is required"
  echo "Usage: footer [breaking:\"<desc>\"] [closes:<nums>] [fixes:<nums>] [refs:<nums>]"
  exit 1
fi

Step 3: Invoke Footer Builder Script

Pass parameters to the utility script for proper formatting:

# Prepare JSON input
cat <<EOF | /home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation/.scripts/footer-builder.py
{
  "breaking": "$breaking",
  "closes": "$closes",
  "fixes": "$fixes",
  "refs": "$refs",
  "reviewed": "$reviewed",
  "signed": "$signed"
}
EOF

The script will:

  • Format BREAKING CHANGE properly
  • Convert issue numbers to proper references
  • Order footer elements correctly
  • Ensure proper spacing and formatting

Step 4: Format Output

Present the generated footer:

FOOTER GENERATED
═══════════════════════════════════════════════

FOOTER:
───────────────────────────────────────────────
<blank line>
<formatted footer content>

VALIDATION:
───────────────────────────────────────────────
✓ Blank line before footer
✓ BREAKING CHANGE format correct
✓ Issue references valid
✓ Proper formatting

COMPONENTS:
───────────────────────────────────────────────
Breaking Changes: <yes/no>
Issues Closed: X
Issues Fixed: X
References: X
Signed-off: <yes/no>

═══════════════════════════════════════════════

Output Format

Return structured output:

  • Formatted footer text
  • Validation results
  • Component breakdown
  • Suggestions (if any)

Error Handling

No parameters provided:

ERROR: At least one footer parameter is required
Usage: footer [breaking:"<desc>"] [closes:<nums>] [fixes:<nums>]

Example: footer breaking:"authentication API changed" closes:123

Invalid issue number format:

ERROR: Invalid issue number format
Expected: closes:123 or closes:123,456
Received: closes:abc

Missing breaking change description:

ERROR: breaking parameter requires description
Usage: footer breaking:"<description of breaking change>"

Example: footer breaking:"API endpoint /auth removed"

Footer Format Rules

Order of Elements:

<blank line>
BREAKING CHANGE: <description>
Closes #<issue>
Fixes #<issue>
Refs #<issue>
Reviewed-by: <name>
Signed-off-by: <name> <email>

Breaking Changes:

  • Always use BREAKING CHANGE: (uppercase, singular)
  • Provide clear description
  • Can also use ! in subject: feat!: change API

Issue References:

  • Use Closes #123 for issues closed by this commit
  • Use Fixes #123 for bugs fixed by this commit
  • Use Refs #123 for related issues
  • Multiple issues: Closes #123, #456

Metadata:

  • Reviewed-by: for code review
  • Signed-off-by: for DCO compliance
  • Custom trailers as needed

Integration with Agent

The commit-assistant agent uses this operation to:

  1. Add breaking change notices
  2. Link commits to issues
  3. Add review metadata
  4. Ensure proper footer formatting

Usage Examples

Example 1: Breaking Change

# Input
/message-generation footer breaking:"authentication API endpoint changed from /login to /auth/login"

# Output
FOOTER:

BREAKING CHANGE: authentication API endpoint changed from /login to
/auth/login

Example 2: Close Issues

# Input
/message-generation footer closes:123,456,789

# Output
FOOTER:

Closes #123, #456, #789

Example 3: Fix and Close

# Input
/message-generation footer fixes:42 closes:100

# Output
FOOTER:

Fixes #42
Closes #100

Example 4: Complete Footer

# Input
/message-generation footer breaking:"remove deprecated API" closes:200 signed:"John Doe <john@example.com>"

# Output
FOOTER:

BREAKING CHANGE: remove deprecated API
Closes #200
Signed-off-by: John Doe <john@example.com>

Example 5: Multiple Issue Fixes

# Input
/message-generation footer fixes:10,20,30 refs:100

# Output
FOOTER:

Fixes #10, #20, #30
Refs #100

Best Practices

Breaking Changes:

  • ✅ "BREAKING CHANGE: API endpoint changed"
  • ❌ "Breaking change: api endpoint changed"
  • ✅ Clear description of what broke
  • ❌ Vague "things changed"

Issue References:

  • ✅ "Closes #123" (actually closes)
  • ❌ "Closes #123" (just mentions)
  • ✅ "Refs #100" (related)
  • ❌ "See issue 100"

Issue Linking Semantics:

  • Closes - Pull request or feature complete
  • Fixes - Bug fix
  • Refs - Related but not closed
  • Resolves - Alternative to Closes

When to Include a Footer

Include footer when:

  • Breaking changes introduced
  • Closes or fixes issues
  • Multiple reviewers
  • DCO/signing required
  • Related work references

Omit footer when:

  • No breaking changes
  • No issue tracking
  • No special metadata
  • Simple standalone commit

Breaking Change Detection

Patterns that indicate breaking changes:

  • API endpoint changes
  • Function signature changes
  • Removed features
  • Changed behavior
  • Dependency major version bumps
  • Configuration format changes

How to communicate breaking changes:

BREAKING CHANGE: <brief description>

<longer explanation of what changed>
<migration path if applicable>

Alternative notation:

feat!: change API endpoint

# The ! indicates breaking change

Footer Templates

Feature with Issue:

Closes #<issue>

Bug Fix:

Fixes #<issue>

Breaking Change with Migration:

BREAKING CHANGE: <what changed>

Migration: <how to update>
Closes #<issue>

Multiple Issues:

Fixes #<bug1>, #<bug2>
Closes #<feature>
Refs #<related>

Signed Commit:

Reviewed-by: <reviewer>
Signed-off-by: <author> <email>

GitHub/GitLab Integration

GitHub Keywords (auto-close issues):

  • Closes, Closed, Close
  • Fixes, Fixed, Fix
  • Resolves, Resolved, Resolve

GitLab Keywords:

  • Closes, Closed, Close (same as GitHub)
  • Fixes, Fixed, Fix
  • Resolves, Resolved, Resolve
  • Implements, Implemented, Implement

Format:

Closes #123                    # Same repository
Closes user/repo#123          # Different repository
Closes https://github.com/... # Full URL

Footer Validation

Valid footer format:

✓ Blank line before footer
✓ BREAKING CHANGE in capitals
✓ Issue numbers have # prefix
✓ Proper token format (Closes, Fixes, etc.)
✓ Valid email in Signed-off-by

Invalid footer format:

✗ No blank line before footer
✗ "Breaking change:" (lowercase)
✗ "Closes 123" (missing #)
✗ "Resolves issue 123" (wrong format)
✗ Invalid email format
Reference in New Issue View Git Blame Copy Permalink