gh-bradleyboehmke-brads-marketplace-document-generator/skills/changelog-standards.md

title, description, tags

title	description	tags
Changelog Standards	Standard changelog format based on Keep a Changelog	changelog versioning documentation standards

Changelog Standards

Metadata

Purpose: Define Standard changelog format and structure Version: 1.0.0

---

Format Specification

Based on Keep a Changelog with Personal extensions.

File Locations

Flexible locations - Teams can choose where to store changelogs:

• CHANGELOG.md (project root) - Most common
• docs/CHANGELOG.md - Documentation directory
• docs/changelog/YYYY.md - Yearly split format for long-lived projects
• Custom paths supported via --path parameter

Auto-detection order:

1. CHANGELOG.md (root)
2. docs/CHANGELOG.md
3. docs/changelog/YYYY.md (current year)
4. Search for **/CHANGELOG.md or **/changelog/*.md

Version Heading Format

Semantic Versioning (SemVer)

## [2.9.0] - 2024-03-15 [MVP]

Calendar Versioning (CalVer)

## [2025.1] - 2025-01-15 [Prototype]

Components:

• Version in brackets: [X.Y.Z] or [YYYY.N]
• ISO date: YYYY-MM-DD
• Tier annotation (optional): [Prototype], [MVP], or [Production]

Changelog Styles

Standard Style (Default)

Uses Keep a Changelog sections in this order:

1. Added - New features
2. Changed - Changes to existing functionality
3. Deprecated - Soon-to-be-removed features
4. Removed - Removed features
5. Fixed - Bug fixes
6. Security - Security fixes

Example:

### Added
- New data validation pipeline for customer segments (#142)
- Support for weekly aggregation in metrics (#156)

### Fixed
- Corrected timezone handling in datetime conversion (#158)

Detailed Style

Uses Highlights + Technical Details format for comprehensive release notes:

Structure:

## [VERSION] - YYYY-MM-DD [TIER]

### Highlights

Brief executive summary (2-4 key points):
- Major feature or capability added
- Significant improvements or changes
- Critical fixes or updates

### Detailed Notes

#### Added
- Feature description with technical details (#PR-number)

#### Changed
- Change description with rationale (#PR-number)

#### Fixed
- Bug fix with context (#PR-number)

Example:

## [2.1.0] - 2025-11-15 [MVP]

### Highlights

- Introduced automated changelog generation from git history
- Enhanced documentation workflow with standards validation
- Improved token efficiency through command optimization

### Detailed Notes

#### Added
- Changelog standardization capability with SemVer and CalVer support (#12)
  - Generate new CHANGELOG.md from git history
  - Update existing changelogs with recent commits
  - Validate format against standards
- Custom path support for flexible changelog locations (#12)

#### Changed
- Optimized git-workflow commands for token efficiency (#23)
- Refactored validation logic to reduce redundancy (#23)

#### Fixed
- Corrected file size validation in pre-commit checks (#23)

Unreleased Section

Always include at top of changelog:

## [Unreleased]

### Added
- Feature in development

### Changed
- Work in progress

Complete Example

# 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/).

## [Unreleased]

### Added
- Experimental feature X

## [2.1.0] - 2025-11-01 [MVP]

### Added
- Customer segmentation model v2
- Automated retraining pipeline

### Changed
- Updated evaluation metrics to include precision-recall curves

### Fixed
- Memory leak in batch processing

## [2.0.0] - 2025-09-15 [MVP]

### Added
- Initial MVP release
- Core recommendation engine
- Integration with production data warehouse

### Changed
- Migrated from prototype to production-ready architecture

[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0

Version Comparison Links

At bottom of changelog, include links:

[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/compare/v1.0.0...v2.0.0
[1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0

Tier Annotations

Map project maturity to versions:

• [Prototype] - Experimental, research phase
• [MVP] - Pilot, initial production deployment
• [Production] - Stable, fully supported release

Writing Guidelines

Good entries:

• Clear, concise descriptions
• User-facing changes (what, not how)
• Business impact when relevant
• Link to issues/PRs for details

Bad entries:

• Implementation details
• Commit messages verbatim
• Internal refactoring (unless user-visible)

Example Good Entry:

### Added
- Support for multi-year trend analysis in dashboard (#142)

Example Bad Entry:

### Changed
- Refactored utils.py to use dataclasses instead of dicts