Happy Changelog
An open workflow framework for managing changelogs through pull request descriptions
Happy Changelog is a free, open workflow framework that eliminates changelog conflicts by moving changelog entries to PR descriptions. It promotes intelligent sorting and merging of entries by change type across multiple PRs and versions, enabling automated version bumping and release notes generation based on semantic versioning principles.
The Problem
Traditional changelog management leads to:
- Frequent merge conflicts in CHANGELOG.md
- Inconsistent formatting across entries
- Manual version bumping prone to errors
- Disconnected release notes
The Solution
Happy Changelog moves entries to PR descriptions and automates the rest:
- Zero changelog merge conflicts
- Consistent entry format
- Enables smart sorting and merging of entries by change type
- Automated semantic versioning
- Integrated release notes
The Happy Changelog Workflow
A simple, three-step process that integrates with your existing development workflow
1. Document in PR
Add a "Changelog" section to your pull request description with appropriate change categories (Added, Changed, Fixed, etc.) and indicate the change level (major/minor/patch).
2. Merge & Automate
When merged, a CI/CD process extracts the changelog entries, updates the CHANGELOG.md file, and bumps the version in package.json based on the highest change level.
3. Release
Create GitHub or GitLab releases with a single command, which automatically compiles all changes since the last release into structured release notes.
Example PR Description Formats
Format 1: Details Element
<details>
<summary>Changelog: minor</summary>
### Added
- Dark mode support to the dashboard
### Fixed
- Alignment issues in mobile navigation
- Documentation for API endpoints
</details>
Format 2: Command Syntax
/changelog minor
### Added
- Dark mode support to the dashboard
### Fixed
- Alignment issues in mobile navigation
- Documentation for API endpoints
/-changelog
Format 3: Markdown Syntax
## Changelog minor
### Added
- Dark mode support to the dashboard
### Fixed
- Alignment issues in mobile navigation
- Documentation for API endpoints
---
Generated Changelog Entry
## v1.2.0
### Added
- Dark mode support to the dashboard
### Fixed
- Alignment issues in mobile navigation
- Documentation for API endpoints
Beyond Simple Concatenation
Happy Changelog promotes intelligent sorting and merging of entries by change type
Multiple PRs → Single Version
PR #123
### Added
- Dark mode support
### Fixed
- Button alignment
PR #124
### Changed
- Updated API endpoints
### Fixed
- Login error handling
PR #125
### Added
- Export to CSV feature
### Deprecated
- Legacy export format
Intelligent Sorting & Organization
Version 1.2.0
### Added
- Dark mode support
- Export to CSV feature
### Changed
- Updated API endpoints
### Fixed
- Button alignment
- Login error handling
### Deprecated
- Legacy export format
Multiple Versions → Single Release
Version 1.1.0
### Added
- User profiles
### Fixed
- Search functionality
Version 1.2.0
### Added
- Dark mode support
- Export to CSV feature
### Fixed
- Button alignment
Version 1.2.1
### Fixed
- Dark mode toggle
### Security
- Updated dependencies
Structured Release Notes
Release v1.2.1
### Added
- User profiles (v1.1.0)
- Dark mode support (v1.2.0)
- Export to CSV feature (v1.2.0)
### Fixed
- Search functionality (v1.1.0)
- Button alignment (v1.2.0)
- Dark mode toggle (v1.2.1)
### Security
- Updated dependencies (v1.2.1)
Why Use Happy Changelog?
Practical benefits for development teams of all sizes
No More Merge Conflicts
Since changelog entries are added to PR descriptions rather than directly to the CHANGELOG.md file, merge conflicts on the changelog become a thing of the past.
Semantic Versioning Compliance
By specifying the change level (major/minor/patch) in the PR description, the framework automatically determines the correct version bump according to semver principles.
Consistent Format
Follows the widely-adopted Keep a Changelog format, ensuring consistency across all entries and making changelogs more readable for users.
Context-Rich Entries
PR descriptions typically contain more context than commit messages, resulting in more meaningful and useful changelog entries that better explain the changes to users.
Automated Release Notes
Generate comprehensive release notes for GitHub or GitLab releases automatically, saving time and ensuring consistency between your changelog and release notes.
Framework Agnostic
Works with any programming language or framework. The workflow principles can be implemented in any CI/CD system and version control platform.
Implementing Happy Changelog
A flexible framework that can be adapted to your workflow
CI/CD Integration
Happy Changelog can be implemented in any CI/CD system. The core workflow involves:
- Extracting changelog entries from PR descriptions when PRs are merged
- Determining the appropriate version bump based on change levels
- Updating the CHANGELOG.md file with the new entries
- Updating version numbers in relevant files (package.json, etc.)
- Creating a Git tag for the new version
Sample implementations:
PR Template
Add a standardized section to your PR template to encourage consistent changelog entries:
Option 1: Details Element
<details>
<summary>Changelog: major|minor|patch</summary>
<!-- Delete sections that are not relevant -->
### Added
-
### Changed
-
### Fixed
-
</details>
Option 2: Command Syntax
/changelog major|minor|patch
<!-- Delete sections that are not relevant -->
### Added
-
### Changed
-
### Fixed
-
/-changelog
Option 3: Markdown syntax
## Changelog major|minor|patch
<!-- Delete sections that are not relevant -->
### Added
-
### Changed
-
### Fixed
-
---
Getting Started
Happy Changelog is a workflow framework, not a specific tool. To implement it in your project:
- Add the PR template to your repository
- Set up CI/CD scripts to process changelog entries from PR descriptions
- Configure version bumping based on change levels
- Implement release note generation for your platform
The Future of Happy Changelog
Expanding the workflow to handle more complex development scenarios
Roadmap
The Happy Changelog project is continuously evolving. Here are some of the key features and improvements planned for future releases:
Prerelease Support
A major goal is to enhance the automated pipelines to include prerelease versions. This will allow tracking of changes across alpha, beta, and release candidate versions, which will then be automatically compacted into a single changelog entry upon final release.
Example workflow:
- Changes are documented in PRs targeting a prerelease branch
- Prerelease versions (1.2.0-beta.1, 1.2.0-beta.2, etc.) are generated with their own changelog entries
- Upon final release, all prerelease changelog entries are intelligently merged into a single, comprehensive entry for version 1.2.0
Enhanced Tooling
Future updates to the changelog-tools package will include more powerful features. Some will include better handling of Markdown source (probably with marked parser) and improved support for various CI/CD platforms.
About the Author
"I grew tired of resolving conflicts in changelogs. I never liked formalized commit messages in PRs. So I decided to create something better."
My journey with changelog management started with frustration and ended with automation. Along the way, I created:
- changelog-tools - an npm package that helped me in initial automation processes (mainly changelog parsing, filtering, and multiversion consolidation).
- Changelog Browser - a mini-project to help people navigate through their changelogs and see clear version differences based on selected version ranges.
- Happy Changelog Workflow - ready-to-use CI/CD example implementations of the Happy Changelog workflow that you can adapt for your projects.
I looooooooooooooooooove automation of boring processes. Processes are for people, not the other way around, so the best process is a seamless one (even if it does a lot underneath the CI/CD mask).