Agent-Skills.md

Agent Skills: Add Changelog Entry

Adds changelog entries to readme.txt following keepachangelog format. Triggered when updating Unreleased section, documenting changes for release, or when user says "add changelog", "update changelog", "log this change".

UncategorizedID: bonny/wordpress-simple-history/changelog
31675

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bonny/WordPress-Simple-History/tree/HEAD/.claude/skills/changelog

Skill Files

Browse the full folder contents for changelog.

Download Skill

Loading file tree…

.claude/skills/changelog/SKILL.md

Skill Metadata

Name
changelog
Description
Adds changelog entries to readme.txt following keepachangelog format. Use when updating the Unreleased section or documenting changes for a release.

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

Location

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