zhongwei/gh-dhofheinz-open-plugins-plugins-marketplace-validator-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-dhofheinz-open-plugins-p…/commands/documentation-validation/validate-changelog.md
Zhongwei Li b727790a9e Initial commit
2025-11-29 18:20:28 +08:00

7.3 KiB
Raw Permalink Blame History

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/):

# 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

    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

# 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

Reference in New Issue View Git Blame Copy Permalink