# Hephaestus Commit Message Standards

## Commit Message Format

### Conventional Commits
Follow conventional commit format for clarity and automation:
```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types
- **feat**: New feature or functionality
- **fix**: Bug fix or error correction
- **docs**: Documentation changes
- **style**: Code formatting, linting, style changes
- **refactor**: Code refactoring without functional changes
- **test**: Adding or updating tests
- **chore**: Maintenance tasks, dependency updates
- **perf**: Performance improvements
- **ci**: CI/CD configuration changes

### Scopes
- **component-management**: Component CRUD operations
- **dependency-analysis**: Component dependency analysis
- **validation**: Component validation logic
- **mcp-tools**: MCP tool registration
- **testing**: Test suite updates
- **models**: Data model changes
- **server**: Server configuration changes
- **docs**: Documentation updates

### Subject Format
- **Imperative mood**: "Add", "Fix", "Update", "Remove", "Implement"
- **Concise**: 50 characters or less
- **Lowercase**: All lowercase
- **No period**: Don't end with period

### Body Format
- **Present tense**: "Adds feature", "Fixes bug", "Updates configuration"
- **What and why**: Explain what was changed and why
- **Breaking changes**: Clearly mark any breaking changes
- **References**: Link to issues, PRs, or related commits

### Examples

#### Feature Addition
```
feat(component-management): Add component CRUD operations

Implements ComponentManager with full CRUD operations for Anvil forms:
- add_component_to_form with intelligent positioning
- update_component_properties with validation
- remove_component_from_form with dependency cleanup
- move_component with layout constraint validation
- list_form_components with filtering and analysis

Supports all 35+ Anvil component types with context-aware
generation based on project modernisation score.

Breaking changes: None
```

#### Bug Fix
```
fix(validation): Resolve component name collision detection

Fixes issue where component validation incorrectly allowed duplicate
names in forms. Added proper name conflict detection in
ComponentOperationsValidator.validate_add_operation method.

Resolves: #123
```

#### Refactoring
```
refactor(models): Simplify component operation data structures

Consolidates ComponentOperation subclasses into single base class with
shared functionality. Reduces code duplication and improves
maintainability of operation tracking.

No functional changes.
```

## Hephaestus-Specific Patterns

### Phase-Based Commits
Reference implementation phases in commit messages:
- **Phase 1**: Core analysis engine
- **Phase 2**: Component management tools
- **Phase 3**: Modern generation tools
- **Phase 4**: Legacy support & migration
- **Phase 5**: Advanced features & polish

### Component Management Commits
For component management features, include:
- **Component Types**: Mention supported Anvil component types
- **Validation**: Reference validation improvements
- **Dependencies**: Note dependency analysis enhancements
- **Performance**: Include operation timing improvements
- **Integration**: Reference MCP tool registration

### Quality Gates
Before committing, ensure:
- **Tests pass**: All relevant tests passing
- **Linting clean**: No ruff issues
- **Type checking**: No basedpyright errors
- **Documentation**: Updated if API changes
- **Breaking changes**: Clearly documented if present

### Multi-line Commits
For complex changes, use detailed body:
```
feat(component-management): Complete Phase 2.1 implementation

Core Implementation:
- ComponentManager with full CRUD operations
- ComponentOperationsValidator with enhanced validation  
- ComponentDependencyAnalyzer for dependency analysis
- Component operation models with comprehensive data structures

MCP Tools Implemented:
- add_component_to_form - Intelligent component addition
- update_component_properties - Safe property updates
- remove_component_from_form - Dependency-aware removal
- move_component - Layout-constrained repositioning
- list_form_components - Inventory with filtering
- analyze_component_dependencies - Dependency mapping
- get_component_impact_analysis - Impact assessment

Key Features:
- All 35+ Anvil component types supported
- Context-aware generation (modern/hybrid/legacy)
- Zero breaking changes to existing forms
- Complete dependency tracking and cleanup
- Performance optimization (< 500ms operations)
- 100% validation coverage
- Rollback capability for all operations

Testing:
- 14 test cases covering all major functionality
- 11 passing tests for core operations
- Tests for validation, dependency analysis, and error handling

Integration:
- Phase 2 ProjectContext integration complete
- FormGenerator extension implemented
- ComponentValidator enhancement complete
- FastMCP server registration complete

This provides critical foundation for Phase 3 generation tools.
```

## Footer Format

### Co-authored
For multiple authors:
```
Co-authored-by: Author Name <author@example.com>
```

### References
Link to related issues:
```
Resolves: #issue-number
Related: #related-issue
```

## Automated Commit Guidelines

### Pre-commit Hooks
- **ruff check**: Ensure code quality
- **basedpyright**: Type checking
- **pytest**: Run relevant tests

### Commit Message Generation
Use structured commit messages for:
- **Clarity**: Easy to understand what changed
- **Searchability**: Findable by type and scope
- **Automation**: Compatible with tooling
- **Consistency**: Follow project standards

### Quality Assurance
- **Review**: All commits should be reviewed
- **Testing**: Ensure tests cover new functionality
- **Documentation**: Update docs for API changes
- **Performance**: Monitor for regressions