222 lines
4.9 KiB
Markdown
222 lines
4.9 KiB
Markdown
---
|
|
title: Changelog Standards
|
|
description: Standard changelog format based on Keep a Changelog
|
|
tags: [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](https://keepachangelog.com/en/1.0.0/) 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)
|
|
```markdown
|
|
## [2.9.0] - 2024-03-15 [MVP]
|
|
```
|
|
|
|
### Calendar Versioning (CalVer)
|
|
```markdown
|
|
## [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**:
|
|
```markdown
|
|
### 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**:
|
|
```markdown
|
|
## [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**:
|
|
```markdown
|
|
## [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:
|
|
```markdown
|
|
## [Unreleased]
|
|
|
|
### Added
|
|
- Feature in development
|
|
|
|
### Changed
|
|
- Work in progress
|
|
```
|
|
|
|
## Complete Example
|
|
|
|
```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/).
|
|
|
|
## [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:
|
|
```markdown
|
|
[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**:
|
|
```markdown
|
|
### Added
|
|
- Support for multi-year trend analysis in dashboard (#142)
|
|
```
|
|
|
|
**Example Bad Entry**:
|
|
```markdown
|
|
### Changed
|
|
- Refactored utils.py to use dataclasses instead of dicts
|
|
```
|