Table of Contents
Who, Why and Benefits
Change Logs are for humans … to gain a high-level understanding of what will evolve when the product update / upgrade is executed.
Helping Change Managers quickly evaluate a dart-board risk profile to business and technical processes.
Helping potiential users get a feel for the volatility of change; occassionally, regularly, security awareness, maximum tested version for support, etc.
A Change Log is a curated timeline of notable changes in each version, that you can skim and identify any topic-of-interest to deep-dive into (if you want too).
A change log should be the source-of-truth for evrything going on under-the-hood in your product.
Guiding Principles
- Change Logs are for humans, not bots.
- Latest version at the top.
- Every version gets an entry.
- Every version has a release date.
- Every version should be linkable.
- Group the same types of changes.
- Use a Semantic Version schema (a design pattern).
- Use Markdown (*.md files) where possible.
Types of Changes
- Add a new feature or story.
- Change an existing feature or story.
- Deprecate notice to remove a feature or story.
- Remove a feature or story. It is gone.
- Fix a Bug, Defect or unreasonable Limit.
- Security improvement against vulnerabilities.
Recommendations
- Use YYYY-MM-DD date format. It is universal and sort friendly.
- All depreciate notices should have plenty of lead time before the remove is actually done. Generally, the more the better.
- One day, mature your product by adding an easy rollback feature.
- Align the product version and git tags for consistency.
- Always share the good, the bad, the ugly and the wins.
Example – Two Change Log Versions
## 0.1.1 - 2024-11-17
- Add website email structure for Email Templates (wpexpertsio) plugin.
- Add shortcode capability to menus, widgets, titles and RankMath plugin.
- Change to use BlockBase 3.1.21 parent theme.
## 0.1.0 - 2024-07-25
- Add initial version created with guidance from [WordPress Developer Handbook - Child Themes](https://developer.wordpress.org/themes/advanced-topics/child-themes/).