docs(AGENTS): update Conventional Commits guidelines and best practices

This commit is contained in:
Julian Pawlowski 2025-12-01 23:48:30 +00:00
parent e156dfb061
commit 369f07ee39

View file

@ -1023,42 +1023,82 @@ Combine into single commit when:
### Conventional Commits Format ### Conventional Commits Format
**Reference:** Follow [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification.
**Structure:** **Structure:**
``` ```
<type>(<scope>): <short summary (max 50-72 chars)> <type>[optional scope]: <description>
<detailed description, wrapped at 72 chars> [optional body]
Impact: <user-visible effects or context for future release notes> [optional footer(s)]
``` ```
**Best Practices:** **Required Elements:**
- **Subject line**: Max 50 chars (hard limit 72), imperative mood ("Add" not "Added") - **type**: Lowercase, communicates intent (feat, fix, docs, etc.)
- **Body**: Wrap at 72 chars, explain WHAT and WHY (not HOW - code shows that) - **description**: Short summary (max 50-72 chars), imperative mood ("add" not "added"), lowercase start, no period
- **Blank line**: Required between subject and body
- **Impact section**: Our addition for release note generation (optional but recommended)
**Types:** **Optional Elements:**
- **scope**: Parentheses after type, e.g., `feat(sensors):` - lowercase, specific area of change
- **body**: Detailed explanation, wrap at 72 chars, explain WHAT and WHY (not HOW - code shows that)
- **footer**: Breaking changes, issue references, or custom fields
**Breaking Changes:**
Use `BREAKING CHANGE:` footer or `!` after type/scope:
```
feat(api)!: drop support for legacy endpoint
BREAKING CHANGE: The /v1/prices endpoint has been removed. Use /v2/prices instead.
```
**Types (Conventional Commits standard):**
- `feat`: New feature (appears in release notes as "New Features") - `feat`: New feature (appears in release notes as "New Features")
- `fix`: Bug fix (appears in release notes as "Bug Fixes") - `fix`: Bug fix (appears in release notes as "Bug Fixes")
- `docs`: Documentation only (appears in release notes as "Documentation") - `docs`: Documentation only (appears in release notes as "Documentation")
- `style`: Code style/formatting (no behavior change, omitted from release notes)
- `refactor`: Code restructure without behavior change (may or may not appear in release notes) - `refactor`: Code restructure without behavior change (may or may not appear in release notes)
- `chore`: Maintenance tasks (usually omitted from release notes) - `perf`: Performance improvement (appears in release notes)
- `test`: Test changes only (omitted from release notes) - `test`: Test changes only (omitted from release notes)
- `style`: Formatting changes (omitted from release notes) - `build`: Build system/dependencies (omitted from release notes)
- `ci`: CI configuration (omitted from release notes)
- `chore`: Maintenance tasks (usually omitted from release notes)
**Scope (optional but recommended):** **Scope (project-specific, optional but recommended):**
- `translations`: Translation system changes - `translations`: Translation system changes
- `config_flow`: Configuration flow changes - `config_flow`: Configuration flow changes
- `sensors`: Sensor implementation - `sensors`: Sensor implementation
- `binary_sensors`: Binary sensor implementation
- `api`: API client changes - `api`: API client changes
- `coordinator`: Data coordinator changes - `coordinator`: Data coordinator changes
- `services`: Service implementations
- `docs`: Documentation files - `docs`: Documentation files
**Custom Footer - Impact Section:**
Add `Impact:` footer for release note generation context (project-specific addition):
```
feat(services): add rolling window support
Implement dynamic 48h window that adapts to data availability.
Impact: Users can create auto-adapting price charts without manual
day selection. Requires config-template-card for ApexCharts mode.
```
**Best Practices:**
- **Subject line**: Max 50 chars (hard limit 72), lowercase, imperative mood
- **Body**: Wrap at 72 chars, optional but useful for complex changes
- **Blank line**: Required between subject and body
- **Impact footer**: Optional but recommended for user-facing changes
### Technical Commit Message Examples ### Technical Commit Message Examples
**Example 1: Bug Fix** **Example 1: Bug Fix**