Initial commit
This commit is contained in:
Zhongwei Li
431
commands/history-analysis/suggest-conventions.md
Normal file
431
commands/history-analysis/suggest-conventions.md
Normal file
@@ -0,0 +1,431 @@
|
||||
# Operation: Suggest Conventions
|
||||
|
||||
**Purpose:** Generate project-specific commit message convention recommendations based on historical analysis and best practices.
|
||||
|
||||
## Parameters
|
||||
|
||||
From `$ARGUMENTS` (after operation name):
|
||||
- `count:N` - Number of commits to analyze (default: 50)
|
||||
- `branch:name` - Branch to analyze (default: current branch)
|
||||
- `format:json|text` - Output format (default: text)
|
||||
- `include_examples:true|false` - Include example commits (default: true)
|
||||
- `priority:high|medium|low|all` - Filter by recommendation priority (default: all)
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Validate Repository
|
||||
|
||||
```bash
|
||||
if ! git rev-parse --git-dir >/dev/null 2>&1; then
|
||||
echo "Error: Not in a git repository"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Gather Historical Data
|
||||
|
||||
Execute analysis operations to collect data:
|
||||
|
||||
**A. Style Analysis:**
|
||||
```bash
|
||||
./.scripts/style-analyzer.sh <count> <branch>
|
||||
```
|
||||
|
||||
**B. Pattern Detection:**
|
||||
```bash
|
||||
./.scripts/pattern-detector.py --count <count> --branch <branch>
|
||||
```
|
||||
|
||||
**C. Scope Extraction:**
|
||||
```bash
|
||||
./.scripts/scope-extractor.sh --count <count> --branch <branch>
|
||||
```
|
||||
|
||||
### 3. Execute Convention Recommender
|
||||
|
||||
Invoke the convention-recommender.py utility script:
|
||||
|
||||
```bash
|
||||
./.scripts/convention-recommender.py --count <count> --branch <branch> --priority <priority>
|
||||
```
|
||||
|
||||
The script will:
|
||||
- Analyze aggregated historical data
|
||||
- Identify current conventions and gaps
|
||||
- Generate recommendations by priority
|
||||
- Provide examples and implementation guidance
|
||||
- Create project-specific guidelines
|
||||
|
||||
### 4. Recommendation Categories
|
||||
|
||||
**A. Format Recommendations**
|
||||
- Commit message structure
|
||||
- Subject line format
|
||||
- Body organization
|
||||
- Footer conventions
|
||||
|
||||
**B. Type Recommendations**
|
||||
- Commonly used types
|
||||
- Type selection guidance
|
||||
- Project-specific type meanings
|
||||
|
||||
**C. Scope Recommendations**
|
||||
- Standard scopes for the project
|
||||
- Scope naming patterns
|
||||
- When to use each scope
|
||||
|
||||
**D. Content Recommendations**
|
||||
- Writing style (imperative mood, tense)
|
||||
- Capitalization and punctuation
|
||||
- Issue reference format
|
||||
- Breaking change documentation
|
||||
|
||||
**E. Process Recommendations**
|
||||
- Pre-commit validation
|
||||
- Atomicity guidelines
|
||||
- Review practices
|
||||
|
||||
### 5. Recommendation Priority Levels
|
||||
|
||||
**HIGH Priority (Critical for consistency):**
|
||||
- Adopt conventional commits if not using (< 50% usage)
|
||||
- Fix major inconsistencies (> 30% deviation)
|
||||
- Establish missing critical patterns
|
||||
|
||||
**MEDIUM Priority (Improve quality):**
|
||||
- Refine existing patterns (50-80% consistency)
|
||||
- Add missing optional elements
|
||||
- Enhance documentation practices
|
||||
|
||||
**LOW Priority (Nice-to-have):**
|
||||
- Fine-tune minor details
|
||||
- Advanced features (co-authors, trailers)
|
||||
- Optimization opportunities
|
||||
|
||||
### 6. Output Structure
|
||||
|
||||
**Text Format (default):**
|
||||
```
|
||||
Project-Specific Commit Convention Recommendations
|
||||
==================================================
|
||||
|
||||
Analysis: 50 commits on branch 'main'
|
||||
Current Consistency: 85/100 (GOOD)
|
||||
Generated: 2024-03-10
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
🔴 HIGH PRIORITY RECOMMENDATIONS
|
||||
|
||||
1. Continue Using Conventional Commits
|
||||
Status: ✓ Already adopted (87% usage)
|
||||
Action: Maintain current practice
|
||||
Benefit: Enables automated changelog, semantic versioning
|
||||
|
||||
Format: <type>(<scope>): <subject>
|
||||
Example from project:
|
||||
✓ feat(auth): implement OAuth2 authentication
|
||||
✓ fix(api): handle null pointer in user endpoint
|
||||
|
||||
2. Standardize Subject Line Length
|
||||
Status: ○ Needs improvement (avg: 47 chars, σ=12)
|
||||
Action: Keep subject lines under 50 characters
|
||||
Current: 15% exceed limit
|
||||
Target: < 5% exceed limit
|
||||
|
||||
✓ Good: "feat(auth): add OAuth provider support"
|
||||
✗ Too long: "feat(auth): implement OAuth2 authentication with support for multiple providers including Google and GitHub"
|
||||
✓ Better: "feat(auth): add OAuth multi-provider support"
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
🟡 MEDIUM PRIORITY RECOMMENDATIONS
|
||||
|
||||
3. Increase Body Usage for Complex Changes
|
||||
Status: ○ Moderate usage (34% of commits)
|
||||
Action: Add body for non-trivial changes
|
||||
Benefit: Better context for code review and history
|
||||
|
||||
When to add body:
|
||||
• Multiple files changed (>3)
|
||||
• Complex logic changes
|
||||
• Breaking changes
|
||||
• Security-related changes
|
||||
|
||||
Example from project:
|
||||
feat(auth): implement OAuth2 authentication
|
||||
|
||||
- Add OAuth2 flow implementation
|
||||
- Support Google and GitHub providers
|
||||
- Include middleware for route protection
|
||||
- Add configuration management
|
||||
|
||||
4. Consistent Issue References
|
||||
Status: ✓ Good usage (67% of commits)
|
||||
Action: Reference issues consistently
|
||||
Current format: "Closes #123", "Fixes #456"
|
||||
Recommendation: Continue current practice
|
||||
|
||||
Patterns detected in project:
|
||||
✓ Closes #123 (45% of references)
|
||||
✓ Fixes #456 (38% of references)
|
||||
✓ Refs #789 (17% of references)
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
🟢 LOW PRIORITY RECOMMENDATIONS
|
||||
|
||||
5. Consider Adding Co-Author Attribution
|
||||
Status: ✗ Rare usage (2% of commits)
|
||||
Action: Add co-authors for pair programming
|
||||
Format: Co-authored-by: Name <email>
|
||||
|
||||
Example:
|
||||
feat(api): add user management endpoint
|
||||
|
||||
Co-authored-by: Jane Doe <jane@example.com>
|
||||
|
||||
6. Document Breaking Changes Explicitly
|
||||
Status: ○ Occasional (8% of commits)
|
||||
Action: Use BREAKING CHANGE footer when applicable
|
||||
|
||||
Format:
|
||||
feat(api): change authentication flow
|
||||
|
||||
BREAKING CHANGE: API now requires OAuth tokens
|
||||
instead of API keys. Update client applications.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📋 PROJECT-SPECIFIC STYLE GUIDE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
COMMIT MESSAGE FORMAT
|
||||
---------------------
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
|
||||
TYPES (in order of frequency)
|
||||
------------------------------
|
||||
feat - New features (35% of commits)
|
||||
fix - Bug fixes (30% of commits)
|
||||
docs - Documentation (16% of commits)
|
||||
refactor - Code restructuring (8% of commits)
|
||||
test - Testing (5% of commits)
|
||||
chore - Maintenance (6% of commits)
|
||||
|
||||
COMMON SCOPES (use these)
|
||||
-------------------------
|
||||
auth - Authentication/authorization (18%)
|
||||
api - Backend API (15%)
|
||||
ui - User interface (12%)
|
||||
db - Database (9%)
|
||||
docs - Documentation (9%)
|
||||
config - Configuration (6%)
|
||||
|
||||
STYLE RULES (current project standards)
|
||||
----------------------------------------
|
||||
✓ Use imperative mood ("add" not "added")
|
||||
✓ Capitalize first letter of subject
|
||||
✓ No period at end of subject
|
||||
✓ Wrap body at 72 characters
|
||||
✓ Blank line between subject and body
|
||||
✓ Reference issues when applicable
|
||||
✓ Use bullet points in body
|
||||
|
||||
EXAMPLES FROM THIS PROJECT
|
||||
---------------------------
|
||||
feat(auth): implement OAuth2 authentication
|
||||
|
||||
- Add OAuth2 flow implementation
|
||||
- Support Google and GitHub providers
|
||||
- Include middleware for route protection
|
||||
|
||||
Closes #123
|
||||
|
||||
---
|
||||
|
||||
fix(api): handle null pointer in user endpoint
|
||||
|
||||
The endpoint was not checking for null user objects
|
||||
before accessing properties, causing crashes.
|
||||
|
||||
Fixes #456
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📊 CONSISTENCY METRICS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Format: 87% ████████████████████████░░░
|
||||
Conventions: 92% ██████████████████████████░
|
||||
Content: 67% ███████████████████░░░░░░░░
|
||||
Overall: 85% █████████████████████░░░░░
|
||||
|
||||
NEXT STEPS
|
||||
----------
|
||||
1. Share this guide with team
|
||||
2. Add to CONTRIBUTING.md
|
||||
3. Configure git commit template
|
||||
4. Set up pre-commit hooks
|
||||
5. Review in team meeting
|
||||
|
||||
AUTOMATION OPPORTUNITIES
|
||||
-------------------------
|
||||
• Pre-commit hook to validate format
|
||||
• Automated changelog generation
|
||||
• Semantic version bumping
|
||||
• Commit message linting (commitlint)
|
||||
```
|
||||
|
||||
**JSON Format:**
|
||||
```json
|
||||
{
|
||||
"analysis_type": "convention_recommendations",
|
||||
"commits_analyzed": 50,
|
||||
"branch": "main",
|
||||
"consistency_score": 85,
|
||||
"generated_date": "2024-03-10",
|
||||
"recommendations": {
|
||||
"high_priority": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Continue Using Conventional Commits",
|
||||
"status": "good",
|
||||
"current_usage": 87,
|
||||
"target_usage": 90,
|
||||
"action": "Maintain current practice",
|
||||
"benefit": "Enables automated tooling",
|
||||
"examples": [
|
||||
"feat(auth): implement OAuth2 authentication",
|
||||
"fix(api): handle null pointer"
|
||||
]
|
||||
}
|
||||
],
|
||||
"medium_priority": [...],
|
||||
"low_priority": [...]
|
||||
},
|
||||
"style_guide": {
|
||||
"format": "<type>(<scope>): <subject>",
|
||||
"types": [
|
||||
{"name": "feat", "percentage": 35, "description": "New features"},
|
||||
{"name": "fix", "percentage": 30, "description": "Bug fixes"}
|
||||
],
|
||||
"scopes": [
|
||||
{"name": "auth", "percentage": 18, "description": "Authentication"},
|
||||
{"name": "api", "percentage": 15, "description": "Backend API"}
|
||||
],
|
||||
"rules": [
|
||||
"Use imperative mood",
|
||||
"Capitalize first letter",
|
||||
"No period at end"
|
||||
]
|
||||
},
|
||||
"automation": [
|
||||
"Pre-commit hook validation",
|
||||
"Automated changelog",
|
||||
"Semantic versioning"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Recommendation Generation Algorithm
|
||||
|
||||
```python
|
||||
def generate_recommendations(analysis_data):
|
||||
"""
|
||||
Generate prioritized recommendations based on analysis.
|
||||
"""
|
||||
recommendations = {
|
||||
'high_priority': [],
|
||||
'medium_priority': [],
|
||||
'low_priority': []
|
||||
}
|
||||
|
||||
# Check conventional commits usage
|
||||
if analysis_data['conventional_commits_pct'] < 50:
|
||||
recommendations['high_priority'].append({
|
||||
'title': 'Adopt Conventional Commits',
|
||||
'action': 'Migrate to conventional commits format',
|
||||
'reason': 'Low usage ({}%)'.format(
|
||||
analysis_data['conventional_commits_pct']
|
||||
)
|
||||
})
|
||||
elif analysis_data['conventional_commits_pct'] < 80:
|
||||
recommendations['medium_priority'].append({
|
||||
'title': 'Increase Conventional Commits Usage',
|
||||
'action': 'Encourage team to use format consistently'
|
||||
})
|
||||
|
||||
# Check subject line length
|
||||
avg_length = analysis_data['avg_subject_length']
|
||||
if avg_length > 60:
|
||||
recommendations['high_priority'].append({
|
||||
'title': 'Reduce Subject Line Length',
|
||||
'action': 'Keep subjects under 50 characters',
|
||||
'current': avg_length
|
||||
})
|
||||
|
||||
# Check imperative mood
|
||||
if analysis_data['imperative_mood_pct'] < 80:
|
||||
recommendations['high_priority'].append({
|
||||
'title': 'Use Imperative Mood Consistently',
|
||||
'action': 'Use "add" not "added", "fix" not "fixed"'
|
||||
})
|
||||
|
||||
# More checks...
|
||||
|
||||
return recommendations
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Insufficient data:**
|
||||
- Warning: "Limited data (< 20 commits), recommendations may be less accurate"
|
||||
- Provide recommendations with confidence scores
|
||||
|
||||
**No patterns detected:**
|
||||
- Return: "No clear patterns detected. Consider establishing conventions."
|
||||
- Suggest: Standard conventional commits format as starting point
|
||||
|
||||
**Mixed conventions:**
|
||||
- Identify: "Multiple convention styles detected (X% conventional, Y% other)"
|
||||
- Recommend: "Migrate to single consistent style"
|
||||
|
||||
## Integration Usage
|
||||
|
||||
**By commit-assistant agent:**
|
||||
```
|
||||
New developer onboarding:
|
||||
→ Invoke: /history-analysis suggest-conventions
|
||||
→ Present: Project-specific style guide
|
||||
→ Configure: Git commit template
|
||||
```
|
||||
|
||||
**By team lead:**
|
||||
```
|
||||
Improving consistency:
|
||||
→ Run: /history-analysis suggest-conventions
|
||||
→ Review: High-priority recommendations
|
||||
→ Implement: Top 3 improvements
|
||||
→ Document: In CONTRIBUTING.md
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Operation succeeds when:
|
||||
- [x] All analysis data gathered
|
||||
- [x] Recommendations prioritized correctly
|
||||
- [x] Style guide generated
|
||||
- [x] Examples provided
|
||||
- [x] Actionable guidance included
|
||||
- [x] Automation opportunities identified
|
||||
|
||||
## Performance
|
||||
|
||||
- **Analysis Time:** ~3-5 seconds for complete analysis
|
||||
- **Recommendation Generation:** ~1 second
|
||||
- **Total Time:** ~4-6 seconds
|
||||
Reference in New Issue
Block a user