peopleforrester Changelog Writer
Create and maintain changelogs following industry standards.
When to Use
- Preparing a new release
- Documenting recent changes
- Creating initial changelog
- Migrating to standard format
Changelog Format
Following Keep a Changelog:
# 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 feature description
### Changed
- Modified behavior description
### Deprecated
- Soon-to-be removed feature
### Removed
- Removed feature description
### Fixed
- Bug fix description
### Security
- Security fix description
## [1.0.0] - 2026-01-15
### Added
- Initial release
- Core functionality
[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0
Change Categories
| Category | Use For |
|---|---|
| Added | New features |
| Changed | Changes in existing functionality |
| Deprecated | Features to be removed in future |
| Removed | Features removed in this release |
| Fixed | Bug fixes |
| Security | Security vulnerability fixes |
Writing Good Entries
Do
### Added
- Add user authentication with JWT tokens
- Add rate limiting (100 requests/minute per IP)
- Add CSV export for reports
### Fixed
- Fix memory leak when processing large files (#234)
- Fix incorrect timezone handling in date picker
Don't
### Added
- Added stuff
- New feature
- Updates
### Fixed
- Fixed bug
- Fix issue
Entry Guidelines
Be Specific
# Bad
- Fixed a bug
# Good
- Fix crash when uploading files larger than 10MB (#156)
Include Context
# Bad
- Changed the API
# Good
- Change `/users` endpoint to require authentication (BREAKING)
Reference Issues/PRs
- Add dark mode support (#234)
- Fix memory leak in image processor (fixes #189)
Indicate Breaking Changes
### Changed
- **BREAKING**: Rename `getUser()` to `fetchUser()` for consistency
- **BREAKING**: Remove deprecated `v1` API endpoints
Conventional Commits to Changelog
Map commit types to changelog categories:
| Commit Type | Changelog Category |
|---|---|
feat: |
Added |
fix: |
Fixed |
docs: |
(usually not included) |
style: |
(usually not included) |
refactor: |
Changed (if user-facing) |
perf: |
Changed |
test: |
(usually not included) |
chore: |
(usually not included) |
BREAKING CHANGE: |
Changed/Removed |
Example Commits to Entries
feat: add user profile page
fix: resolve login timeout issue (#123)
feat!: change authentication to OAuth 2.0
Becomes:
### Added
- Add user profile page
### Changed
- **BREAKING**: Change authentication to OAuth 2.0
### Fixed
- Resolve login timeout issue (#123)
Version Numbering
Following Semantic Versioning:
MAJOR.MINOR.PATCH
1.0.0 → 1.0.1 (patch: bug fixes)
1.0.1 → 1.1.0 (minor: new features, backward compatible)
1.1.0 → 2.0.0 (major: breaking changes)
When to Bump
| Change Type | Version Bump |
|---|---|
| Bug fix (backward compatible) | PATCH |
| New feature (backward compatible) | MINOR |
| Breaking change | MAJOR |
| Security fix | PATCH (or MINOR if new feature) |
Release Checklist
When preparing a release:
- Move items from
[Unreleased]to new version section - Add release date:
## [1.2.0] - 2026-01-15 - Update comparison links at bottom
- Remove empty categories
- Review for clarity and completeness
- Commit changelog with version bump
Automation Tools
Conventional Changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s
Release Please
# .github/workflows/release.yml
- uses: google-github-actions/release-please-action@v4
with:
release-type: node
Changesets
npx changeset # Create changeset
npx changeset version # Update versions
Template: Initial Changelog
# 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]
## [0.1.0] - YYYY-MM-DD
### Added
- Initial release
- [List initial features]
[Unreleased]: https://github.com/user/repo/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0