---

name: create-release-notes description: Create or update product-update / release-notes content for a given OpenMetadata/Collate patch version across getcollate, openmetadata-site, and docs-om. Sources getcollate's changelog from openmetadata-collate + OpenMetadata + ai-platform; openmetadata-site's from OpenMetadata only; docs-om reuses openmetadata-site's already-written content, reformatted into its Mintlify snippet structure. Filters to customer-facing changes only, runs each target's own doc-review checklist, verifies every link live, and requires explicit approval before any commit. user-invocable: true argument-hint: "<version, e.g. 2.0.4> [--targets=getcollate,openmetadata-site,docs-om|all] [--skip-docs-om]" allowed-tools:

• Bash
• Read
• Edit
• Write
• Agent

---

Create Release Notes

Produces the release-notes/product-update content for one patch version, for up to three targets, following the exact process worked out interactively across the getcollate v2.0.1–v2.0.3 and v1.13.5–v1.13.6 releases. Read references/process.md before doing any real work — it has the full step-by-step mechanics, the per-target repo config, and every gotcha this process has actually hit.

When to activate

The user asks to create, draft, or update release notes / product updates / a changelog for a specific version, for getcollate, openmetadata-site, docs-om, or "all three" / "everywhere."

Repos this touches

All three are expected as sibling directories next to this one (~/Documents/GitHub/<repo>), already cloned:

| Repo | Role | |---|---| | getcollate | Collate's own site. Output: content/product-updates/vX.Y.Z.md | | openmetadata-site | OSS-only public site. Output: content/product-updates/vX.Y.Z.md (same format, independent id/versions.json, OSS-only content) | | docs-om | OSS docs site. Output: snippets/releases/X.Y.Z.mdx, imported into vX.Y.x/releases/X.Y-release.mdx |

If any expected repo isn't present at that path, stop and ask for its location rather than guessing or skipping it silently.

High-level flow (detail in references/process.md)

Run this once per target the user asked for, in this order: getcollate → openmetadata-site → docs-om (docs-om depends on openmetadata-site's finished content, so it must run last, and only after openmetadata-site's file is written — it is never independently re-derived from commits).

For getcollate and openmetadata-site (same mechanics, different source-repo set and content scope — see the table in references/process.md §1):

1. cd into the repo, git checkout main && git pull.
2. Determine the previous version and next id from versions.json.
3. Create a new branch: product-updates/vX.Y.Z.
4. Resolve the commit range per source repo (tag-to-tag if the next version's tag already exists, else tag-to-branch-HEAD with the re-verification caveat in references/process.md §2).
5. Fetch, paginate, filter, categorize, bundle (§3–§5).
6. Write the file, update versions.json.
7. Customer-facing filter pass (§6) — re-read every bullet, drop anything with no stated end-user/admin-facing symptom.
8. Doc-review pass using that repo's own .ai/doc-review/ checklist (§7).
9. Live link-check every citation (§8).
10. Run the repo's build (yarn build for both Next.js sites) (§9).
11. Start the local server and give the user the preview URL. Do not commit. Wait for the user to say to commit, exactly as they asked.

For docs-om (§10 — a reformat, not a re-derivation):

1. cd into docs-om, git checkout main && git pull, new branch release-notes/vX.Y.Z.
2. Take the finished, already-approved openmetadata-site content for this version (not a fresh commit pull) and wrap it into an <Update> snippet per references/process.md §10.
3. Add the new snippet's import + <ReleaseNotes /> tag at the top of the matching vX.Y.x/releases/X.Y-release.mdx, update the "Upgrade to X" card text.
4. Run docs-om's own .ai/doc-review/ checklist against the new snippet (its rules may differ from openmetadata-site/getcollate's).
5. Live link-check again (the GitHub-release link line is new to this format and easy to typo).
6. Preview (Mintlify dev server if available, otherwise render the mdx mentally and show the user the file) and wait for commit approval.

Non-negotiable checks (every target, every run)

These came from real mistakes made while building this process by hand — see references/process.md §11 for the full incident behind each one:

• Verify every commit's merge timestamp falls strictly between the previous and current release tags. A commit that merges after the target tag was cut does not belong in that release, even if its PR title matches the theme — cite it in the next version instead.
• Cite the actual merged/backport PR, never a referenced issue number or an earlier PR the commit message happens to mention in passing. Verify with gh api repos/<owner>/<repo>/pulls/<n> before trusting any number.
• Never fabricate a commit SHA for a fallback link. If citing a raw commit instead of a PR, fetch the real full SHA first.
• Cap every bundled bullet at 3 PR links. Split into two bullets if a natural bundle would exceed that.
• Collapse a fix that landed as matching PRs in both OpenMetadata and openmetadata-collate down to the OpenMetadata link only — they are the same fix, not two.
• Link labels are plain [#NNNNN] — no Collate/OSS/AI Platform prefix in the visible text (the URL itself already disambiguates).
• No trailing period after the date in frontmatter or in versions.json entries for files this skill creates — check the target repo's own existing convention before assuming, since it can differ per repo/file vintage.
• Bold the symptom, not the fix — every bullet title states the problem a user or admin would recognize; the sentence after the colon states what changed and, where it isn't obvious, why it matters.

Output discipline

• Never commit or push without the user explicitly saying to, even if everything passed every check. Build success and a clean doc-review are not the same thing as approval.
• Never touch yarn.lock or public/sitemap.xml on purpose — if yarn install/yarn build regenerates them as a side effect, git checkout -- them back before staging anything, and don't stage them even if the user says "commit everything."
• One branch per repo per version. Don't reuse a branch across versions, and don't put more than one version's content in a single branch/PR unless the user asks for that explicitly.