changelog
Add an entry to the changelog in readme.txt following the project's changelog format. Use when updating readme.txt, adding to Unreleased section, documenting changes for a release, or when the user says "add changelog" or "update changelog".
When & Why to Use This Skill
This Claude skill streamlines the maintenance of project changelogs within files. By adhering to 'Keep a Changelog' standards and WordPress developer best practices, it ensures that software updates are documented clearly, consistently, and with a focus on end-user impact. It automates the categorization of changes (Added, Fixed, Security, etc.) and maintains the proper structure of the 'Unreleased' section, making it an essential tool for maintaining professional repository documentation.
Use Cases
- Software Release Preparation: Automatically organizing and formatting developer notes into a professional changelog before a new version launch.
- Maintaining WordPress Plugins: Ensuring readme.txt files meet WordPress.org standards for clear, user-friendly update logs to improve plugin transparency.
- Standardizing Repository Documentation: Enforcing a uniform writing style and structure for changelogs across multi-developer projects to ensure consistency.
- Reducing Documentation Debt: Enabling developers to instantly record changes in the correct format using simple natural language commands like 'add changelog' during the development process.
| name | changelog |
|---|---|
| description | Add an entry to the changelog in readme.txt following the project's changelog format. Use when updating readme.txt, adding to Unreleased section, documenting changes for a release, or when the user says "add changelog" or "update changelog". |
Add Changelog Entry
Add a changelog entry to the Simple History plugin's readme.txt file.
Instructions
- Ask the user for the changelog entry text (one line summary of the change)
- Determine the category - Each entry must be in one of these categories:
- Added - New features or functionality
- Changed - Changes to existing functionality
- Fixed - Bug fixes
- Deprecated - Features marked for removal
- Removed - Features that were removed
- Security - Security-related fixes or improvements
- Read the
readme.txtfile to find the## Changelogsection - Locate the
### Unreleasedsubsection - Add the new entry under the appropriate category within Unreleased, or at the top if no categories exist yet
- Follow the exact format:
- Start with hyphen and 3 spaces:
- - Begin with the category verb: "Fixed...", "Added...", "Changed...", etc.
- Be concise and user-focused (explain the user-facing issue/feature, not technical implementation)
- End with a period
- Start with hyphen and 3 spaces:
- Show the user the added entry and confirm it looks correct
Format Examples
Good examples from existing changelog:
- Fixed post creation via Gutenberg autosave not being logged, causing email reports to show 0 posts created.- Add developer mode badge to the page header.- Fixed timezone and date handling issues in email reports.- Add WordPress VIP Go coding standards for enterprise compatibility.- Fixed post creation via Gutenberg autosave not being logged. [#599](https://github.com/bonny/WordPress-Simple-History/issues/599)
Guidelines
- Be specific: Mention the feature/component affected (e.g., "email reports", "Gutenberg autosave")
- User-focused: Explain what users will notice, not how it was implemented
- Concise: Keep to one line when possible
- Active voice: "Fixed X" not "X was fixed"
- Link to GitHub issue or pull request if available
WordPress Changelog Best Practices
Based on WordPress Developer Blog guidance:
Writing Style
- Write for end-users, not developers - Avoid technical jargon
- Be specific, not vague - "Fixed a PHP 8.2 deprecation warning causing admin dashboard errors" NOT "Bug fixes"
- Explain the impact - Include context about why changes matter (performance, security, workflow improvements)
- Use accessible language - Avoid cultural references or overly technical terminology
Structure
- Use clear category labels: Added, Changed, Fixed, Deprecated, Removed, Security
- Maintain consistency across releases
- Each entry should be actionable and descriptive
Good vs Bad Examples
❌ Problematic:
- "Bug fixes"
- "Various improvements"
- "Updated code"
✅ Effective:
- "Fixed post creation via Gutenberg autosave not being logged, causing email reports to show 0 posts created"
- "Added developer mode badge to improve debugging workflow"
- "Fixed timezone handling issues that caused email reports to show incorrect dates"
File Location
- File:
readme.txt(in project root) - Section:
## Changelog→### Unreleased
Notes
- If "Unreleased" section doesn't exist, create it right after "## Changelog"
- Entries use format from https://keepachangelog.com and WordPress best practices
- Most recent entries appear first in the list