feat(changelog): Phase 3 - Issue Forms + render + structured webhook

[ton77v]

Why

Phase 3 of the UI-for-Changelog cutover. Companion to:

• beshu-tech/ror-api#86 — tracker
• beshu-tech/ror-api#91 — webhook accepts new structured payload (already deployed to prod 2026-05-13, smoke test passed)
• readonlyrest-docs#314 — 66-version YAML migration (merged)

The merge of THIS PR is the actual cutover. After merge:

• Maintainers file new changelog entries via Issue Forms instead of editing changelog.md
• changelog.md becomes auto-generated from changelog/*.yaml
• Webhook to ror-api uses new event-typed structured payload
• Non-maintainer issues auto-close

What lands

Workflows

File	Purpose
maintainer_gate.yml	Close + lock changelog issues from non-OWNER/MEMBER/COLLABORATOR (<30s)
changelog_form.yml	Parse form → write changelog/<version>.yaml → open/refresh PR
render_changelog.yml	ajv schema validation + filename↔version check; on push to master, regen changelog.md
changelog_watch.yml	MODIFIED — fires on changelog/*.yaml changes, sends event-typed structured payload

Templates

• .github/ISSUE_TEMPLATE/changelog-entry.yml — 2-field form (version + notes textarea)
• .github/ISSUE_TEMPLATE/config.yml — disables blank issues

Schema + config

• .github/schemas/changelog-entry.schema.json — single source of YAML truth. Includes optional components_raw for hash parity with stored LLM descriptions.
• .github/changelog-config.yml — auto_merge: false (default). Flip to true once trusted to make form PRs auto-merge.

Modified changelog_watch.yml payload

Before (changelog.md diff):

{ "changelog_diff": "<git unified diff>" }

After (per-version event):

{ "event": "version_added | version_modified | version_deleted",
  "version": "1.69.0",
  "yaml": "<full YAML content>" }

One POST per changed YAML in the push. ror-api PR #91 accepts both formats during 1-week dual-window (legacy find_versions_affected kept as fallback).

Bot-authored render commits don't loop

render_changelog.yml pushes changelog.md regens back to master. changelog_watch.yml paths filter is changelog/*.yaml only → bot's changelog.md commits don't re-trigger the watch.

Required repo settings (apply BEFORE merge)

These won't function without these — same settings already applied on ton77v/changelog-forms-demo (see demo PLAN.md):

# Allow Actions to create PRs (form action needs this)
gh api -X PUT repos/beshu-tech/readonlyrest-docs/actions/permissions/workflow \
  -F default_workflow_permissions=read -F can_approve_pull_request_reviews=true

# Auto-delete branches on merge + allow auto-merge
gh api -X PATCH repos/beshu-tech/readonlyrest-docs \
  -F allow_auto_merge=true -F delete_branch_on_merge=true

(Need admin permissions on the repo.)

Verification after merge

1. File a test changelog issue from your maintainer account → expect:

   • [Changelog X.Y.Z] <summary> title (auto-renamed)
   • Bot PR opened against master with changelog/X.Y.Z.yaml
   • Comment on issue linking to PR
   • Issue auto-closed

2. File a test issue from a non-maintainer account → expect auto-close + lock <30s

3. Merge the bot's test PR → expect:

   • changelog.md regenerated by render workflow (auto-commit by github-actions[bot])
   • changelog_watch.yml fires → POSTs new structured payload → ror-api receives + queues try_release_update for the version
   • Check ror-api prod logs: just -g prod logs ror-portal --since 10m | grep -i changelog

4. Delete a test YAML → render workflow regenerates changelog.md without it, watch sends version_deleted event, ror-api logs + skips.

Rollback path

If anything regresses:

1. Revert this PR (single commit on master)
2. ror-api still accepts legacy changelog_diff payload (PR ROR 1.29.0 release #91 kept the fallback)
3. Restore old changelog_watch.yml (the modified file is the only one with a prior version on master)

Phase 4 (next, ~1 week later)

After 1 week of clean dual-window operation:

• Drop find_versions_affected + legacy changelog_diff branch in ror-api update_changelog()
• Drop parse_changelog() (line 65); rewire parse_changelog_structured to iterate YAMLs
• Retarget detailed_changelog.py source from MD parsing → YAML loading (keeps GitBook integration intact)

🦀 sent by Claude Code

[ton77v]

After this merges: follow-up sync needed

The default branch in this repo is `develop` but the changelog-form flow has to live on `master` (`changelog_watch.yml` fires on master push). After this PR merges:

1. Rebase + ready the draft sync PR: #316 — `master → develop` back-merge
2. Merge chore: sync master into develop (after Phase 3 cutover) #316 to keep develop in sync (so future `develop → master` release merges don't conflict)

Same pattern as prior maintenance (`c215bd3 Merge branch 'master' into develop`). #316 has the exact rebase commands in its body.

Also applies retroactively to #314 — content is on master but not develop. #316 carries both forward in one PR.

🦀 sent by Claude Code

[coutoPL]

LGTM