changelog

name	changelog
description	Adds changelog entries to readme.txt following keepachangelog format. Use when updating the Unreleased section or documenting changes for a release.
allowed-tools	Read, Edit

Add Changelog Entry

Add entries to the Simple History plugin's readme.txt changelog.

Workflow

1. Ask user for the change description (if not provided)
2. Determine category: Added, Changed, Fixed, Deprecated, Removed, Security
3. Add entry under ## Changelog → ### Unreleased
4. Confirm with user

Format

-   Fixed post creation via Gutenberg autosave not being logged. [#599](https://github.com/bonny/WordPress-Simple-History/issues/599)

• Start with - (hyphen + 3 spaces)
• Do NOT repeat the category verb — the heading already says Added/Changed/Fixed, so don't start entries with "Added...", "Fixed...", etc.
• Link GitHub issue/PR if available
• End with period

Writing Guidelines

Changelogs are for humans, not machines. Write for both technical and non-technical WordPress users.

Write for the user:

• Explain what changed from the user's perspective, not what you did in the code
• Provide context and scope: instead of "Optimized query" write "Improved performance on sites with large activity logs"
• Replace jargon with clarity: avoid acronyms, internal class names, or hook names unless the audience is developers
• Be specific: "Fixed timezone handling in email reports" not "Bug fixes"
• Active voice: "Fixed X" not "X was fixed"

Be honest and complete:

• Never hide breaking changes, deprecations, or security fixes
• Be upfront about what changed and why — users trust changelogs that are transparent
• Include all notable user-facing changes; selective entries undermine credibility
• Mark experimental features with the 🧪 **Experimental** — prefix (see "Experimental features" section below)

Keep it concise:

• One bullet per change, one or two sentences max
• Don't duplicate commit messages — curate and translate them into user-facing language
• Group related small changes into a single entry rather than listing each separately
• Omit internal refactors, code cleanup, and dev tooling changes unless they affect users
• Omit new PHP/JS functions, helpers, or APIs — these are internal and not user-facing (e.g., don't list Helpers::get_filtered_history_url())
• Cut implementation detail. Filter names, fallback chains, caching strategy, byte limits, index prefix lengths — these belong in the PR description, not the changelog. Lead with the user-visible effect; stop before the "how it works" explanation

Too long → tightened (real example):

❌ New installs now create the history tables with `$wpdb->get_charset_collate()` (matching
   WordPress core's pattern since 4.2) instead of a hardcoded `CHARSET=utf8`. On modern hosts
   this means tables are created as `utf8mb4`, so they can store 4-byte UTF-8 characters
   like emoji in event context — previously a post title with an emoji could silently drop
   the entire context row, leaving log entries like `Updated ""` with no user attribution.
   The contexts table's `key` index is now a 191-char prefix index so it stays under
   InnoDB's 767-byte limit on older row formats. Existing installs are unchanged by this
   release; a follow-up will add an opt-in conversion path for older tables.

✅ New installs create history tables as `utf8mb4` (using `$wpdb->get_charset_collate()`),
   so emoji and other 4-byte UTF-8 characters in event context are preserved instead of
   silently dropping the entire context row. Existing installs are unchanged; an opt-in
   conversion path for older tables will follow.

What was cut: WP core history ("since 4.2"), the broken-log example (Updated ""), and the InnoDB 767-byte index reasoning. What was kept: the user-visible effect (emoji preserved, context not dropped) and the scope note (existing installs unchanged, follow-up coming).

Don't write:

• "Bug fixes" or "Various improvements" (too vague, tells users nothing)
• "Updated code" or "Minor changes" (meaningless)
• Raw commit messages or git log dumps
• Internal hook/filter names in user-facing entries (put in developer docs instead)

Categories

Use these standard categories from Keep a Changelog:

• Added — New features and capabilities
• Changed — Modifications to existing functionality
• Deprecated — Features that will be removed in a future release
• Removed — Features that have been eliminated
• Fixed — Bug fixes
• Security — Vulnerability patches (always include these, never hide them)

Experimental features

Features gated behind the experimental features setting use a consistent format that signals the gating and invites curiosity.

Format:

-   🧪 **Experimental** — Description of the feature, written like any other entry.

Rules:

• Lead with 🧪 **Experimental** — (test-tube emoji + bold label + em-dash + space).
• Don't add "Requires experimental features to be enabled" or trailing "(experimental)" — the prefix already says it.
• Place experimental entries at the bottom of their subsection (Added/Changed/Fixed/Security). Stable items first, experimental opt-ins after.
• If a feature also has a developer-facing filter or hook to toggle it, mention that in the body of the entry, not as boilerplate.
• Don't repeat the marker on continuation entries — every experimental bullet stands alone.

Preamble in Unreleased:

The Unreleased section starts with a one-line blockquote that explains what the marker means. This lives once at the top of Unreleased — don't duplicate it in older releases:

> 🧪 **Experimental** entries are gated behind the experimental features setting (Settings → Simple History → Experimental). Enable it to try them, then share feedback so we know what to ship for everyone.

Why this format:

• The 🧪 emoji reads as "try this, it's new" — a curiosity hook, not a warning.
• Leading the line (rather than trailing) makes it scannable: a reader skimming the changelog can spot experimental items immediately.
• Placing them last in each section means readers focused on stable shipping changes can stop scanning at the first 🧪.
• The format matches the style already used for headings in the readme description (🔍 ✨ 🚀 💚).

Examples:

✅ 🧪 **Experimental** — Failed application password authentication on REST API and XML-RPC requests is now logged as a warning…
✅ 🧪 **Experimental** — "History" column on post and page list tables showing recent activity at a glance.
❌ "History" column on post and page list tables… (experimental)            (trailing tag — old format)
❌ "History" column on post and page list tables… Requires experimental features to be enabled.   (boilerplate phrase — superseded by the 🧪 prefix)
❌ 🧪 History column…                                                        (missing **Experimental** label)

Unreleased Section

Always maintain an ### Unreleased section at the top of the changelog. This lets users see what's coming and makes it easy to promote entries into a versioned release.

When releasing, move Unreleased entries into a new versioned section with the release date.

Release: the "What's new" update notice

At release time, besides the changelog, add the in-plugin "Highlights in this version" notice that users see when they update. It's separate from readme.txt:

• File: inc/services/class-simple-history-updates.php
• Register add_filter( 'simple_history/pluginlogger/plugin_updated_details/simple-history/X.Y.Z', [ $this, 'on_plugin_updated_details_X_Y_Z' ] ); in loaded()
• Add a matching on_plugin_updated_details_X_Y_Z() method returning 3 short highlight bullets + the release-post link (copy the previous version's method)

Preview it with the dev WP-CLI command (needs SIMPLE_HISTORY_DEV). Note the subcommand uses underscores, not dashes:

docker compose run --rm wpcli_mariadb \
  simple-history dev add_plugin_update_message --prev-version=<PREV> --version=<NEW>

This logs a fake "plugin updated" event; the highlights render in its event-details panel in wp-admin. --version defaults to the installed version. Premium has its own on_plugin_updated_details_* in the premium plugin — preview with --plugin=simple-history-premium/simple-history-premium.php.

Examples

✅ Post creation via Gutenberg autosave not being logged, causing email reports to show 0 posts created.
✅ Developer mode badge to improve debugging workflow.
✅ Performance on sites with large activity logs improved by optimizing database queries.
✅ `simple_history_log()` function — use `SimpleHistory\log()` instead. Will be removed in 6.0.
❌ Added developer mode badge (redundant — heading already says "Added")
❌ Fixed post creation (redundant — heading already says "Fixed")
❌ Bug fixes
❌ Updated code
❌ Refactored SimpleHistoryLogQuery class
❌ Various improvements and optimizations

References

• WordPress Developer Blog: The Importance of a Good Changelog
• Keep a Changelog: https://keepachangelog.com

Location

• File: readme.txt (project root)
• Section: ## Changelog → ### Unreleased
• If Unreleased doesn't exist, create it after ## Changelog