diff --git a/CHANGELOG.md b/CHANGELOG.md index 92381d63..107e0be1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,14 @@ See history/YYMMDD-ROADMAOTOPIC/ directories for planning information of closed - Test coverage: 25 tests for semantic validators (16 section/content + 9 link), 100% passing - Full documentation: Semantic validation guide in SCHEMA_MANAGEMENT_GUIDE.md with examples - Complements existing structural AST validation for complete document compliance checking +- **Changelog Schema**: Production schema for validating CHANGELOG.md files following Keep a Changelog format + - Schema file: `changelog-schema-v1.0.md` validates version history structure and formatting + - Enforces Unreleased section presence (required) + - Validates version format: `[X.Y.Z] - YYYY-MM-DD` with semantic versioning + - Validates change type subsections: Added, Changed, Deprecated, Removed, Fixed, Security + - Content pattern validation for version sections, date formats (ISO 8601), and change types + - Demonstrates real-world schema system usage: "The release that validates itself" + - Successfully validates project CHANGELOG.md with all semantic checks passing ### Changed - **Directory Reorganization**: diff --git a/markitect/schemas/changelog-schema-v1.0.md b/markitect/schemas/changelog-schema-v1.0.md new file mode 100644 index 00000000..61edb796 --- /dev/null +++ b/markitect/schemas/changelog-schema-v1.0.md @@ -0,0 +1,348 @@ +--- +schema: changelog-schema-v1.0 +version: "1.0" +domain: changelog +description: "JSON schema for Keep a Changelog format with version history validation" +created: "2026-01-06" +author: "MarkiTect Schema System" +--- + +# Changelog Schema v1.0 + +## Overview + +This schema validates CHANGELOG.md files following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. It enforces: + +- Unreleased section presence (required) +- Version section format: `[X.Y.Z] - YYYY-MM-DD` +- Standard change type subsections +- Semantic versioning adherence +- ISO 8601 date formatting + +## Purpose + +Ensures changelog files maintain consistent structure and formatting across releases, facilitating: +- Automated release note generation +- Version history tracking +- Release validation workflows +- Documentation consistency + +## Schema Definition + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "title": "Changelog Schema", + "description": "Validates Keep a Changelog format for project changelogs", + + "x-markitect-metadata": { + "schema_name": "changelog-schema-v1.0", + "version": "1.0", + "domain": "changelog", + "created": "2026-01-06", + "author": "MarkiTect Schema System" + }, + + "x-markitect-sections": { + "[Unreleased]": { + "classification": "required", + "heading_level": 2, + "error_message": "Unreleased section is mandatory for tracking upcoming changes", + "content_instruction": "Use ## [Unreleased] heading. Section can be empty if no unreleased changes.", + "alternatives": ["UNRELEASED", "Unreleased"] + }, + "Added": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "New features added in this release" + }, + "Changed": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "Changes to existing functionality" + }, + "Deprecated": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "Features that will be removed in future versions" + }, + "Removed": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "Features removed in this release" + }, + "Fixed": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "Bug fixes in this release" + }, + "Security": { + "classification": "optional", + "heading_level": 3, + "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "content_instruction": "Security fixes and vulnerabilities addressed" + } + }, + + "x-markitect-content-control": { + "title": { + "required_patterns": [ + "^# Changelog$" + ], + "content_quality": { + "min_words": 1, + "max_words": 1 + }, + "error_message": "Title must be exactly '# Changelog'" + }, + "introduction": { + "recommended_patterns": [ + "Keep a Changelog", + "Semantic Versioning" + ], + "content_instruction": "Introduction should reference Keep a Changelog and Semantic Versioning standards" + }, + "unreleased_section": { + "required_patterns": [ + "## \\[Unreleased\\]" + ], + "content_quality": { + "min_words": 0 + }, + "error_message": "Unreleased section must use format: ## [Unreleased]" + }, + "version_section": { + "required_patterns": [ + "## \\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2}" + ], + "content_instruction": "Version sections must follow format: ## [X.Y.Z] - YYYY-MM-DD", + "error_message": "Version sections must use semantic versioning (X.Y.Z) with ISO 8601 dates (YYYY-MM-DD)" + }, + "change_types": { + "recommended_patterns": [ + "### Added", + "### Changed", + "### Deprecated", + "### Removed", + "### Fixed", + "### Security" + ], + "content_instruction": "Use standard Keep a Changelog change type subsections", + "error_message": "Change types should be one of: Added, Changed, Deprecated, Removed, Fixed, Security" + }, + "link_references": { + "recommended_patterns": [ + "\\[Keep a Changelog\\]\\(https://keepachangelog\\.com", + "\\[Semantic Versioning\\]\\(https://semver\\.org" + ], + "content_instruction": "Include reference links to Keep a Changelog and Semantic Versioning" + } + }, + + "x-markitect-validation-rules": { + "version_format": { + "pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]", + "description": "Version must follow semantic versioning: [MAJOR.MINOR.PATCH]" + }, + "date_format": { + "pattern": "\\d{4}-\\d{2}-\\d{2}", + "description": "Date must be in ISO 8601 format: YYYY-MM-DD" + }, + "version_ordering": { + "rule": "descending", + "description": "Versions should be listed in descending order (newest first)" + }, + "unreleased_position": { + "rule": "first_section", + "description": "Unreleased section must come before all version sections" + } + }, + + "properties": { + "headings": { + "type": "object", + "description": "Document heading structure", + "properties": { + "level_1": { + "type": "array", + "description": "Title heading (should be 'Changelog')", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "pattern": "^Changelog$" + } + } + }, + "minItems": 1, + "maxItems": 1 + }, + "level_2": { + "type": "array", + "description": "Version sections ([Unreleased] and [X.Y.Z] - YYYY-MM-DD)", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "pattern": "^(\\[Unreleased\\]|\\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2})$" + } + } + }, + "minItems": 1, + "maxItems": 100 + }, + "level_3": { + "type": "array", + "description": "Change type subsections (Added, Changed, etc.)", + "minItems": 0, + "maxItems": 500 + } + }, + "required": ["level_1", "level_2"] + }, + "paragraphs": { + "type": "array", + "description": "Introduction and change descriptions", + "minItems": 1, + "maxItems": 5000 + }, + "lists": { + "type": "array", + "description": "Change item lists", + "minItems": 0, + "maxItems": 1000 + } + }, + "required": ["headings", "paragraphs"] +} +``` + +## Usage Examples + +### Valid Changelog Structure + +```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] + +## [1.0.0] - 2026-01-06 + +### Added +- New feature A +- New feature B + +### Fixed +- Bug fix for issue #123 +``` + +### Validation Command + +```bash +# Ingest schema +markitect schema-ingest markitect/schemas/changelog-schema-v1.0.md + +# Validate changelog +markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md --semantic +``` + +## Validation Checks + +### Required Elements +- ✅ Title: Must be "# Changelog" +- ✅ Unreleased section: `## [Unreleased]` must be present +- ✅ Version format: `## [X.Y.Z] - YYYY-MM-DD` for all releases + +### Recommended Elements +- ⭐ Introduction paragraph referencing Keep a Changelog +- ⭐ Semantic Versioning reference +- ⭐ At least one change type subsection per version + +### Content Patterns +- Version sections use semantic versioning (MAJOR.MINOR.PATCH) +- Dates in ISO 8601 format (YYYY-MM-DD) +- Change types: Added, Changed, Deprecated, Removed, Fixed, Security +- Bullet point lists for change items + +## Common Validation Errors + +### Missing Unreleased Section +**Error**: "Unreleased section is mandatory for tracking upcoming changes" +**Fix**: Add `## [Unreleased]` section at the top of version history + +### Invalid Version Format +**Error**: "Version sections must use semantic versioning (X.Y.Z)" +**Fix**: Use format `## [1.0.0] - 2026-01-06` not `## Version 1.0.0` + +### Invalid Date Format +**Error**: "Date must be in ISO 8601 format: YYYY-MM-DD" +**Fix**: Use `2026-01-06` not `Jan 6, 2026` or `01/06/2026` + +### Missing Change Type Subsections +**Warning**: "Version should have at least one change type subsection" +**Fix**: Add `### Added`, `### Fixed`, or other change type heading + +## Schema Extension Notes + +### Future Enhancements + +This schema could be extended with: + +1. **System Call Validation** (`x-markitect-validation-hooks`): + - Verify git tags match CHANGELOG versions + - Check version ordering consistency + - Validate date chronology + +2. **Agent Validation** (`x-markitect-validation-agents`): + - Semantic consistency checking + - Duplicate entry detection + - Version numbering logic validation + +3. **Cross-Reference Validation**: + - Link validation to issue trackers + - Commit hash verification + - Release note completeness checking + +## Keep a Changelog Standard + +This schema enforces the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) principles: + +- **Changelogs are for humans**, not machines +- **One entry per version** +- **Group changes by type** (Added, Changed, etc.) +- **Versions and dates** for each release +- **Latest version first** +- **Unreleased section** for upcoming changes + +Combined with [Semantic Versioning](https://semver.org/), this enables consistent, readable version history. + +## Version History + +- **1.0** (2026-01-06): Initial schema release + - Basic structure validation + - Version and date format checking + - Change type subsection validation + - Keep a Changelog compliance + +## Related Schemas + +- `schema-schema-v1.0.md` - Metaschema for validating schemas +- `manpage-schema-v1.0.md` - Schema for manual pages +- `api-documentation-schema-v1.0.md` - Schema for API documentation + +## License + +Part of MarkiTect Schema System