diff --git a/.agents/skills/release-changelog-authoring/SKILL.md b/.agents/skills/release-changelog-authoring/SKILL.md new file mode 100644 index 000000000..f1b939013 --- /dev/null +++ b/.agents/skills/release-changelog-authoring/SKILL.md @@ -0,0 +1,20 @@ +--- +name: release-changelog-authoring +description: Author or revise Popup Maker release notes, CHANGELOG.md entries, readme.txt changelogs, or GitHub release descriptions using the supported categorized or prefixed formats. Use whenever preparing a release or changing shipped-release documentation. +--- + +# Release changelog authoring + +Read [the format reference](references/formats.md) before editing release notes. + +1. Describe notable user-visible outcomes. Omit internal tooling and implementation details unless they affect users, integrators, compatibility, privacy, or security. +2. Use one format consistently within a release: + - Prefer categorized Keep a Changelog-style sections for substantial releases. + - A compact prefixed list is valid for small releases when every classified item uses an explicit delimiter such as `Fixed: `. +3. Preserve links, emphasis, nested lists, and explanatory paragraphs. Nested material must be indented beneath its parent list item; never infer parentage from proximity alone. +4. Keep a feature entry concise. Link to a dedicated explainer when the supporting material is longer than a short nested list. +5. Update the current branch's `CHANGELOG.md`, `readme.txt`, and GitHub release draft/source together when the repository workflow requires them. +6. Treat existing tags as immutable. Never rewrite files in an existing tag or move/recreate a shipped tag. An explicitly authorized correction may update the GitHub release description without altering its tag, commit, or assets. +7. Before publishing or rewriting historical notes, show or save a reviewable diff and verify headings, list nesting, links, and user-facing meaning. +8. If syncing WordPress content, operate only on the `ca_release` post type. Do not modify pages, posts, settings, or any other post type. + diff --git a/.agents/skills/release-changelog-authoring/references/formats.md b/.agents/skills/release-changelog-authoring/references/formats.md new file mode 100644 index 000000000..a1ea2a1bd --- /dev/null +++ b/.agents/skills/release-changelog-authoring/references/formats.md @@ -0,0 +1,69 @@ +# Supported changelog formats + +## Categorized format (preferred) + +Use the relevant Keep a Changelog categories: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`. Repositories may use an established user-facing alias such as `Improvements` for `Changed`, but do not invent a new synonym within a release. + +```markdown +## v1.2.0 - 2026-08-21 + +### Added + +- **Split testing** — Compare popup variants and measure the winner. [Learn more](https://example.com/feature/) + + Supported experiment types: + + - Popup versus popup. + - Content variants. + - Holdout tests. + +### Fixed + +- Prevented duplicate conversion attribution during checkout. +``` + +The blank line and indentation keep the paragraph and nested list inside the parent `
  • `. Use four spaces when a renderer or linter does not reliably accept two. + +## Compact prefixed format + +Use this for short releases without section headings. The prefix must be followed by `:` so ordinary prose beginning with “fixed” or “added” is not misclassified. + +```markdown +- Added: Support for holdout tests. +- Changed: Improved purchase attribution accuracy. +- Fixed: Prevented duplicate conversion attribution during checkout. +- Security: Hardened webhook signature validation. +``` + +Accepted canonical prefixes are `Added:`, `Changed:`, `Deprecated:`, `Removed:`, `Fixed:`, and `Security:`. Existing repositories may retain `Improvement:` as a compatibility alias for `Changed:`. Prefer `Fixed:` over `Fix:` in new entries; parsers may continue accepting `Fix:` for historical content. + +When displaying a prefix as a label, remove it only when the delimiter is present. Capitalize the remaining sentence without otherwise rewriting it. + +## WordPress readme.txt + +Use WordPress.org heading syntax while preserving the same category and list hierarchy: + +```text += 1.2.0 - 2026-08-21 = + += Added = + +* **Split testing** — Compare popup variants and measure the winner. + += Fixed = + +* Prevented duplicate conversion attribution during checkout. +``` + +Keep the public readme concise. Put extensive tutorials or feature explanations in durable documentation and link to them. + +## Review checklist + +- Version and date match the release metadata. +- Every item is under exactly one category. +- A compact release uses delimited prefixes consistently. +- Nested paragraphs/lists remain children of the intended item. +- Links and emphasis survive conversion between Markdown and readme.txt. +- No item is truncated in the middle of a list element. +- No existing tag, tagged file tree, release asset, or shipped commit changes. + diff --git a/.github/workflows/changelog-backfill.yml b/.github/workflows/changelog-backfill.yml index 9bb556611..5cf39d032 100644 --- a/.github/workflows/changelog-backfill.yml +++ b/.github/workflows/changelog-backfill.yml @@ -25,7 +25,7 @@ permissions: jobs: backfill: name: Review or run Core changelog backfill - uses: code-atlantic/release-changelog-action/.github/workflows/backfill-releases.yml@7af898299ba0704f385b236569ead17850388437 + uses: code-atlantic/release-changelog-action/.github/workflows/backfill-releases.yml@e21a0260c19a4723ffe1145014a916d3c48936e2 with: product-key: core expected-repository: PopupMaker/Popup-Maker @@ -34,5 +34,6 @@ jobs: dry-run: ${{ inputs.dry_run }} secrets: WORDPRESS_URL: ${{ secrets.WORDPRESS_URL }} + WORDPRESS_ACCESS_TOKEN: ${{ secrets.WORDPRESS_ACCESS_TOKEN }} WORDPRESS_USERNAME: ${{ secrets.WORDPRESS_USERNAME }} WORDPRESS_APPLICATION_PASSWORD: ${{ secrets.WORDPRESS_APPLICATION_PASSWORD }} diff --git a/.github/workflows/changelog-sync.yml b/.github/workflows/changelog-sync.yml index ad82796bd..ed99eda2e 100644 --- a/.github/workflows/changelog-sync.yml +++ b/.github/workflows/changelog-sync.yml @@ -16,12 +16,13 @@ permissions: jobs: changelog: name: Sync review-required WordPress draft - uses: code-atlantic/release-changelog-action/.github/workflows/sync-release.yml@7af898299ba0704f385b236569ead17850388437 + uses: code-atlantic/release-changelog-action/.github/workflows/sync-release.yml@e21a0260c19a4723ffe1145014a916d3c48936e2 with: product-key: core expected-repository: PopupMaker/Popup-Maker release-id: ${{ format('{0}', github.event.release.id || inputs.release_id) }} secrets: WORDPRESS_URL: ${{ secrets.WORDPRESS_URL }} + WORDPRESS_ACCESS_TOKEN: ${{ secrets.WORDPRESS_ACCESS_TOKEN }} WORDPRESS_USERNAME: ${{ secrets.WORDPRESS_USERNAME }} WORDPRESS_APPLICATION_PASSWORD: ${{ secrets.WORDPRESS_APPLICATION_PASSWORD }} diff --git a/AGENTS.md b/AGENTS.md index da7829e50..6c80171cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -486,6 +486,12 @@ DO NOT FORGET: ## Workflow Notes +### Release changelogs + +- For any release-note, `CHANGELOG.md`, `readme.txt`, or GitHub release work, follow `.agents/skills/release-changelog-authoring/SKILL.md` and its format reference. +- Keep existing tags immutable. Corrections to historical GitHub release descriptions do not authorize changes to tagged files, commits, tags, or assets. +- Any WordPress changelog migration or sync must be limited to the `ca_release` post type. + ### Package Management Considerations - When adding new packages, we have to update webpack config, tsconfigs, dependency extraction plugin package list AND Assets.php appropriately