Story: Hotfix: release notes export produces broken/relative id links
Table of Contents
This page documents a story in Sprint 24. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Sprint 24's exported `release_notes.md` (the GitHub release body) is free of `[BROKEN LINK: <uuid>]` placeholders, and every `id:` link in it resolves to a live, absolute URL on the published site. The fix lives in the shared exporter so it applies to every future sprint's release notes automatically, not just this one.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 24 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-08-03 |
Acceptance
- No `BROKEN LINK` placeholders in the exported `release_notes.md` for sprint 24.
- `id:` links in the exported markdown resolve to real, live `https://orestudio.github.io/OreStudio/…` URLs (verified via curl against both a local build and the real published site).
- The fix lives in `ores-build-release-notes.el` (the shared exporter), so it applies to every future sprint automatically.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Hotfix: release notes export produces broken/relative id links | DONE | 2026-08-03 | 2026-08-03 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. |
| Implement Hotfix: release notes export produces broken/relative id links | DONE | 2026-08-03 | 2026-08-03 | Initial task for: Hotfix: release notes export produces broken/relative id links |
Decisions
- `id:` links resolve to the published site (`https://orestudio.github.io/OreStudio/…`), not a relative `.md` path or a `github.com/…/blob/main/….org` link, since a release note ships as a standalone GitHub release body with none of the rest of the doc tree alongside it — mirrors `ores-build-manual.el`'s `ores/manual-id-export` convention.
- The custom `id` export handler must check `(org-export-derived-backend-p backend 'md)`, not `'gfm` — ox-gfm derives from ox-md and link transcoding reports the backend as `md`.
Out of scope
Result
Fixed `ores-build-release-notes.el` to (1) scan the whole repo with `org-id-update-id-locations` before export, and (2) resolve `id:` links to absolute `https://orestudio.github.io/OreStudio/…` URLs via a custom export handler. Re-exported sprint 24's `release_notes.md`: zero `BROKEN LINK` placeholders remain, and the resolved links were verified live (HTTP 200) against the published GitHub Pages site. The fix is in the shared exporter, so it applies to every future sprint's release notes going forward.