itechmeat/changelog

Changelog

Format specification for CHANGELOG.md based on Keep a Changelog 1.1.0.

Language Requirement (Mandatory)

• All changelog content MUST be written in English.
• If source information is provided in another language, translate it to English.
• Do not mix languages within the same changelog.

Quick Reference

File Header

# 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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Section Structure

## [Unreleased]

### Added

- New feature description

## [1.0.0] - 2024-01-15

### Added

- Feature A
- Feature B

### Changed

- Modified behavior X

### Fixed

- Bug fix Y

Types of Changes

| Type | Purpose | | ------------ | --------------------------------- | | Added | New features | | Changed | Changes in existing functionality | | Deprecated | Soon-to-be removed features | | Removed | Now removed features | | Fixed | Bug fixes | | Security | Vulnerabilities |

Format Rules

Version Header

## [X.Y.Z] - YYYY-MM-DD

• Version in brackets, linked to comparison
• Date in ISO 8601 format (YYYY-MM-DD)

Date-Based Versioning (Alternative)

For projects using date-based versioning instead of semver:

## [YYYY-MM-DD]

Use current date instead of [Unreleased]. This project uses date-based versioning.

Yanked Releases

## [0.0.5] - 2014-12-13 [YANKED]

Use when version was pulled due to serious bug or security issue.

Comparison Links (at file end)

[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

Guiding Principles

1. For humans, not machines — Write clear, readable entries
2. Entry for every version — Document all releases
3. Group same types — Keep Added/Changed/Fixed together
4. Linkable versions — Use comparison links
5. Latest first — Reverse chronological order
6. Show release dates — Use ISO 8601 format
7. State versioning scheme — Mention Semantic Versioning if used

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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New authentication method

## [1.2.0] - 2024-01-20

### Added

- User profile page
- Export to CSV functionality

### Changed

- Improved loading performance by 40%

### Deprecated

- Legacy API endpoint `/api/v1/users` (use `/api/v2/users`)

### Fixed

- Login timeout issue on slow connections

## [1.1.0] - 2024-01-10

### Added

- Dark mode support

### Security

- Fixed XSS vulnerability in comment field

## [1.0.0] - 2024-01-01

### Added

- Initial release with core features
- User registration and login
- Dashboard with analytics

[unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0

Bad Practices

Commit log diffs

Don't dump git log into changelog:

• Full of noise (merge commits, obscure titles)
• Not human-readable
• Mixes important and trivial changes

Ignoring deprecations

Don't skip deprecation notices:

• Users need to know what will break
• Document deprecations before removals
• List breaking changes clearly

Confusing dates

Don't use regional date formats:

• Use ISO 8601: YYYY-MM-DD
• Avoids ambiguity (is 01/02/2024 Jan 2 or Feb 1?)

Inconsistent changes

Don't document only some changes:

• Changelog should be single source of truth
• Important changes must be mentioned
• Consistently updated

Writing Tips

Good Entry Examples

### Added

- OAuth2 authentication with Google and GitHub providers
- Rate limiting for API endpoints (100 req/min)

### Changed

- Database queries now use prepared statements for better security
- Upgraded dependency `lodash` from 4.17.20 to 4.17.21

### Fixed

- Memory leak in WebSocket connection handler
- Race condition in concurrent file uploads

Entry Guidelines

• Review current git changes (diff or changed files list) before drafting; ensure all material changes are covered.
• Start with verb or noun describing the change
• Be specific (mention affected component/endpoint)
• Reference issue/PR numbers when relevant: (#123)
• Keep entries concise but informative
• Omit empty sections (do not include a section header if there are no entries for it)

File Naming

Required: CHANGELOG.md (uppercase). Do not use lowercase or alternative names.

Do not use alternative filenames.

GitHub Releases vs CHANGELOG.md

| Aspect | GitHub Releases | CHANGELOG.md | | --------------- | --------------- | ----------------- | | Portability | GitHub-only | Universal | | Discoverability | Less visible | Standard location | | Version control | Separate UI | In repository | | Diff links | Manual setup | Easy to add |

GitHub Releases can complement but shouldn't replace CHANGELOG.md.

Conventional Commits Integration

Changelogs work best with Conventional Commits format:

| Commit Type | Changelog Section | | ----------------- | -------------------- | | feat: | Added | | fix: | Fixed | | perf: | Changed | | refactor: | Changed | | docs: | (often omitted) | | BREAKING CHANGE | Highlight in Changed | | Security fix | Security | | revert: | Removed or Fixed |

Automated Generation

Tools that parse Conventional Commits and generate changelogs:

• conventional-changelog
• semantic-release
• release-please

See commits skill for commit message format.

Workflow Integration

Unreleased Section Pattern

1. Add changes to ## [Unreleased] during development
2. At release time, rename to ## [X.Y.Z] - YYYY-MM-DD
3. Create new empty ## [Unreleased] section
4. Add comparison link for new version

Pre-commit Checklist

Before release:

• [ ] All notable changes documented
• [ ] Unreleased section moved to version
• [ ] Date added in ISO 8601 format
• [ ] Comparison link added
• [ ] Breaking changes highlighted
• [ ] Deprecations documented

Critical Prohibitions

• Do not use git log as changelog
• Do not omit breaking changes or deprecations
• Do not use ambiguous date formats
• Do not leave changelog inconsistently updated
• Do not forget to update Unreleased → version at release
• Do not write changelog entries in any language other than English

README Synchronization

After writing changelog, review the project's main README.md:

1. Check for outdated information — features, skills, tools lists
2. Add new entries — if changelog introduces new skills, features, or components
3. Remove deprecated items — if changelog removes functionality
4. Update descriptions — if changelog changes existing functionality

What to sync:

• Skills/features tables
• Compatibility lists
• Installation instructions
• Links and references

What NOT to sync:

• Changelog content itself (no duplication)
• Version history
• Detailed change descriptions

Do NOT mention README.md updates in CHANGELOG — README synchronization is implied and should not be logged as a separate change.

Links

• Official specification: https://keepachangelog.com/en/1.1.0/
• Semantic Versioning: https://semver.org/spec/v2.0.0.html
• Related: commits skill — Conventional Commits format

Templates

• CHANGELOG.template.md — Empty template to start
• CHANGELOG.example.md — Complete working example