gh-dhofheinz-open-plugins-plugins-marketplace-validator-plugin/commands/documentation-validation/validate-changelog.md

## Operation: Validate CHANGELOG Format

Validate CHANGELOG.md format compliance with "Keep a Changelog" standard.

### Parameters from $ARGUMENTS

- **file**: Path to CHANGELOG file (optional, default: CHANGELOG.md)
- **format**: Expected format (optional, default: keepachangelog)
- **strict**: Enable strict validation (optional, default: false)
- **require-unreleased**: Require [Unreleased] section (optional, default: true)

### CHANGELOG Requirements

**Keep a Changelog Format** (https://keepachangelog.com/):

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Added
- New features not yet released

## [1.0.0] - 2025-01-15
### Added
- Initial release feature
### Changed
- Modified behavior
### Fixed
- Bug fixes
```

**Required Elements**:
1. **Title**: "Changelog" or "Change Log"
2. **Version Headers**: `## [X.Y.Z] - YYYY-MM-DD` format
3. **Change Categories**: Added, Changed, Deprecated, Removed, Fixed, Security
4. **Unreleased Section**: `## [Unreleased]` for upcoming changes
5. **Chronological Order**: Newest versions first

**Valid Change Categories**:
- **Added**: New features
- **Changed**: Changes in existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Fixed**: Bug fixes
- **Security**: Security vulnerability fixes

### Workflow

1. **Locate CHANGELOG File**
   ```
   Check for CHANGELOG.md in plugin root
   Also check: CHANGELOG, CHANGELOG.txt, changelog.md, HISTORY.md
   If not found, report as missing (WARNING, not CRITICAL)
   ```

2. **Execute CHANGELOG Validator**
   ```bash
   Execute .scripts/changelog-validator.sh with parameters:
   - File path to CHANGELOG
   - Expected format (keepachangelog)
   - Strict mode flag
   - Require unreleased flag

   Script returns:
   - has_title: Boolean
   - has_unreleased: Boolean
   - version_headers: Array of version entries
   - categories_used: Array of change categories
   - issues: Array of format violations
   - compliance_score: 0-100
   ```

3. **Validate Version Headers**
   ```
   For each version header:
   - Check format: ## [X.Y.Z] - YYYY-MM-DD
   - Validate semantic version (X.Y.Z)
   - Validate date format (YYYY-MM-DD)
   - Check chronological order (newest first)

   Common violations:
   - Missing brackets: ## 1.0.0 - 2025-01-15 (should be [1.0.0])
   - Wrong date format: ## [1.0.0] - 01/15/2025
   - Invalid semver: ## [1.0] - 2025-01-15
   ```

4. **Validate Change Categories**
   ```
   For each version section:
   - Check for valid category headers (### Added, ### Fixed, etc.)
   - Warn if no categories used
   - Recommend appropriate categories

   Invalid category examples:
   - "### New Features" (should be "### Added")
   - "### Bugs" (should be "### Fixed")
   - "### Updates" (should be "### Changed")
   ```

5. **Calculate Compliance Score**
   ```
   score = 100
   score -= (!has_title) ? 10 : 0
   score -= (!has_unreleased) ? 15 : 0
   score -= (invalid_version_headers × 10)
   score -= (invalid_categories × 5)
   score -= (wrong_date_format × 5)
   score = max(0, score)
   ```

6. **Format Output**
   ```
   Display:
   - ✅/⚠️/❌ File presence
   - ✅/❌ Format compliance
   - ✅/⚠️ Version headers
   - ✅/⚠️ Change categories
   - Compliance score
   - Specific violations
   - Improvement recommendations
   ```

### Examples

```bash
# Validate default CHANGELOG.md
/documentation-validation changelog file:CHANGELOG.md

# Validate with custom path
/documentation-validation changelog file:./HISTORY.md

# Strict validation (all elements required)
/documentation-validation changelog file:CHANGELOG.md strict:true

# Don't require Unreleased section
/documentation-validation changelog file:CHANGELOG.md require-unreleased:false

# Part of full documentation check
/documentation-validation full-docs path:.
```

### Error Handling

**Error: CHANGELOG not found**
```
⚠️ WARNING: CHANGELOG.md not found in <path>

Remediation:
1. Create CHANGELOG.md in plugin root directory
2. Use "Keep a Changelog" format (https://keepachangelog.com/)
3. Include [Unreleased] section for upcoming changes
4. Document version history with proper headers

Example:
# Changelog

## [Unreleased]
### Added
- Features in development

## [1.0.0] - 2025-01-15
### Added
- Initial release

Note: CHANGELOG is recommended but not required for initial submission.
It becomes important for version updates.
```

**Error: Invalid version header format**
```
❌ ERROR: Invalid version header format detected

Invalid headers found:
- Line 10: "## 1.0.0 - 2025-01-15" (missing brackets)
- Line 25: "## [1.0] - 01/15/2025" (invalid semver and date format)

Correct format:
## [X.Y.Z] - YYYY-MM-DD

Examples:
- ## [1.0.0] - 2025-01-15
- ## [2.1.3] - 2024-12-20
- ## [0.1.0] - 2024-11-05

Remediation:
1. Add brackets around version numbers: [1.0.0]
2. Use semantic versioning: MAJOR.MINOR.PATCH
3. Use ISO date format: YYYY-MM-DD
```

**Error: Missing Unreleased section**
```
⚠️ WARNING: Missing [Unreleased] section

The Keep a Changelog format recommends an [Unreleased] section for tracking
upcoming changes before they're officially released.

Add to top of CHANGELOG (after title):

## [Unreleased]
### Added
- Features in development
### Changed
- Planned changes
```

**Error: Invalid change categories**
```
⚠️ WARNING: Non-standard change categories detected

Invalid categories found:
- "### New Features" (should be "### Added")
- "### Bug Fixes" (should be "### Fixed")
- "### Updates" (should be "### Changed")

Valid categories:
- Added: New features
- Changed: Changes in existing functionality
- Deprecated: Soon-to-be removed features
- Removed: Removed features
- Fixed: Bug fixes
- Security: Security vulnerability fixes

Remediation:
Replace non-standard categories with Keep a Changelog categories.
```

### Output Format

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHANGELOG VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File: ✅ CHANGELOG.md found

Format: Keep a Changelog
Compliance: <0-100>% ✅/⚠️/❌

Structure:
✅ Title present
✅ [Unreleased] section present
✅ Version headers formatted correctly
✅ Change categories valid

Version Entries: <count>
- [1.0.0] - 2025-01-15 ✅
- [0.2.0] - 2024-12-20 ✅
- [0.1.0] - 2024-11-05 ✅

Change Categories Used:
✅ Added (3 versions)
✅ Changed (2 versions)
✅ Fixed (3 versions)

Issues Found: <N>

Violations:
<List specific issues if any>

Recommendations:
1. Add Security category for vulnerability fixes
2. Expand [Unreleased] section with upcoming features
3. Add links to version comparison (optional)

Overall: <PASS|WARNINGS|FAIL>
```

### Integration

This operation is invoked by:
- `/documentation-validation changelog file:CHANGELOG.md` (direct)
- `/documentation-validation full-docs path:.` (as part of complete validation)
- `/validation-orchestrator comprehensive path:.` (via orchestrator)

Results contribute to documentation quality score:
- Present and compliant: +10 points
- Present but non-compliant: +5 points
- Missing: 0 points (warning but not blocking)

**Request**: $ARGUMENTS