# Release Checklist

A practical pre-release checklist for this plugin, covering the things that have actually caused
problems in past releases. This is a working checklist, not an architectural contract — see
`docs/ATTRIBUTION_DATASET.md` for the Canonical Attribution Dataset's own Release Gates, which this
checklist complements rather than duplicates.

---

## 1. Changelog hygiene (readme.txt)

This came up directly: `readme.txt`'s Changelog section has a hard 5,000-character limit enforced by
WordPress.org's readme parser. Exceeding it doesn't cause an error — it silently truncates the
section, which can cut an entry off mid-sentence on the public plugin page.

Before every release:

- [ ] **Check the current size** of the Changelog section:
  ```
  awk '/== Changelog ==/,0' readme.txt | wc -c
  ```
- [ ] If it's approaching **3,500–4,000 characters**, archive older entries before adding a new one
  rather than after — don't wait for Plugin Check to catch it.
- [ ] **Keep each new entry to 1–3 sentences.** A short entry that says what changed and why is more
  useful on the public listing than a full engineering write-up. Save deep technical detail for the
  commit/PR itself, not the public changelog.
- [ ] **Archive, never delete.** When trimming, move the removed entries into
  `docs/CHANGELOG-ARCHIVE.md` verbatim — the full version history should always exist somewhere, just
  not necessarily inside the WordPress.org-parsed file.
- [ ] After trimming, re-run the size check above and confirm the result is comfortably under 5,000
  (leave headroom for the entry you're about to add).

## 2. Canonical Attribution Dataset compliance

For any release that touches attribution fields, persistence, or reporting, walk the **Release
Gates** section of `docs/ATTRIBUTION_DATASET.md` in full:

- [ ] Dataset parity
- [ ] Normalization parity
- [ ] Reports parity
- [ ] CSV parity
- [ ] Plugin Check
- [ ] PHPCS
- [ ] QA
- [ ] Upgrade compatibility
- [ ] Fresh install compatibility

That document is the source of truth for what those gates mean — this checklist doesn't restate the
definitions, only reminds you they exist and to run them.

## 3. Structural / HTML sanity (admin pages)

Not every bug is a logic bug. The v1.13.2 Column Visibility break was a nested `<form>` inside
another `<form>` — invalid HTML that broke a feature with no PHP-level symptom at all. Before
releasing any change to an admin-page template:

- [ ] Grep the touched template file(s) for `<form` and `</form>` and manually confirm every open/close
  pair is a genuine sibling or parent/child relationship — never nested.
- [ ] If a control needs to submit independently from a surrounding form, use the HTML5 `form=""`
  attribute on the button, pointing to a separate, non-nested `<form>` — don't nest.
- [ ] Manually load the admin page in a browser and inspect the DOM (dev tools) to confirm the
  rendered structure matches what was intended, not just the source template.

## 4. Version and packaging

- [ ] Version bumped consistently in: plugin header comment, `SHULMANATTRIB_VERSION` constant,
  `assets/js/utm-tracker.js` header comment, and `readme.txt`'s `Stable tag`.
- [ ] New changelog entry added (see §1 for size discipline).
- [ ] If schema changed: DB version constant(s) bumped and `dbDelta`-compatible (additive only).
- [ ] Brace/parenthesis/PHP-tag balance manually verified on every touched file (no PHP CLI is
  available in this working environment, so this substitutes for a linter — re-run after every edit,
  not just once at the end).
- [ ] `docs/ATTRIBUTION_DATASET.md` diffed against the previous version — confirm it's either
  unchanged (expected for most releases) or deliberately updated with a stated reason.

## 5. Backward compatibility

- [ ] No existing meta key, cookie name, option name, or CSV column *position* renamed or removed.
- [ ] New CSV columns appended, never inserted mid-row.
- [ ] Existing user preferences (e.g. column visibility) verified to survive an upgrade unchanged.
- [ ] A fresh install and an upgrade-from-previous-version are both considered — a fix for one should
  not be assumed to also cover the other.

## 6. Final QA pass

- [ ] Run Plugin Check and PHPCS in an actual WordPress environment (not available in this sandbox —
  every release up to this point has shipped without this step actually being run here, so it
  remains the single biggest gap in this checklist until a real environment is available for it).
- [ ] Manually exercise the specific feature(s) changed this release, on a real WordPress install.
- [ ] Re-read the changelog entry once more before publishing — does it match what actually shipped?