// Use when adding a changelog entry for a branch. Use after completing work on a feature, fix, or improvement that is user-facing.
| name | writing-changelog |
| description | Use when adding a changelog entry for a branch. Use after completing work on a feature, fix, or improvement that is user-facing. |
User-facing changes MUST have a changelog entry. Each entry is a small Markdown file created by the pnpm changelog:add command for free-plugin changes. Follow the steps below in order.
Compare the current branch against the base branch to understand what changed.
Read the relevant code changes to understand the user-facing impact.
Pick one valid type that best describes the change: Added, Improved, Fixed, Changed, Updated, Removed
Write a short, user-facing description:
Good examples:
Fix email rendering issue in OutlookAdd ability to filter subscribers by purchase dateImprove performance of subscriber listing pageBad examples:
Refactor SubscriberRepository query method (technical jargon)Fix bug in NewsletterEntity::getStatus() (class/method names)Update dependencies. (trailing punctuation)Run the command from the repo root for free-plugin changes:
pnpm changelog:add --type=<type> --description="<description>"
For premium-only changes, use the premium plugin's Robo command directly because there is no root pnpm wrapper for it yet:
cd mailpoet-premium && ./do changelog:add --type=<type> --description="<description>"
Most branches need a changelog. Skip only when changes are:
When in doubt, add a changelog entry.
Use when investigating a failing test — reported via a CircleCI job/build URL, or output from a local test run. Triggers on phrases like "this test failed", "debug this CI failure", "why did the nightly fail?", "investigate the failure on <branch>", or any message pasting a CircleCI URL with failure context. Guides the investigator to diagnose, fix, and verify the fix locally. Stops there — committing, opening a PR, or writing a changelog is the caller's call (see `creating-pull-requests`, `writing-changelog`).
Linting and code quality workflows for MailPoet development (PHP, JS/TS, CSS/SCSS). Use when fixing code style or following the development workflow.
Use when running MailPoet tests — executing a full suite, running a single file or single test, running in debug/multisite mode, or shelling into the test container. Triggers on phrases like "run the unit tests", "run this test file", "execute the integration suite", "kick off acceptance tests", "rerun the failed tests". Does not cover authoring tests (see writing-tests) or investigating a failed CI run (see debugging-failed-tests).
Use when authoring tests for MailPoet — adding a new test case, picking the right test type, choosing a name, structuring the file, deciding what belongs in unit vs integration vs acceptance. For invoking the test runner (running a file, the whole suite, premium variants, debug mode) see running-tests. For investigating a CI failure see debugging-failed-tests.
Use when adding or changing SQL joins, WHERE comparisons, temporary tables, segment filters, subscriber synchronization, or WooCommerce queries that compare text columns across WordPress, WooCommerce, and MailPoet tables.
Use when a new WooCommerce or WordPress beta / release candidate is available and you need to test MailPoet's compatibility against it. Triggers on phrases like "test against WC beta", "test MailPoet on WP beta", "compatibility test", "new WooCommerce version", "new WordPress version".