docs(changelog): add changelog page with release-stub automation - #66
Merged
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
djsauble
marked this pull request as ready for review
August 7, 2026 23:54
tanjadev
reviewed
Aug 12, 2026
Replaces flox.dev/changelog (a hand-curated YAML in floxwebsite, stale
since May) with a Changelog tab built on Mintlify <Update> components.
Structure: changelog.mdx is the CURRENT year's page — its frontmatter
title names the year in the left sidebar, and the stable /changelog URL
and RSS feed at /changelog/rss.xml never move, so feed subscribers never
resubscribe across year rollovers. Past years live at
changelog/<year>.mdx, listed newest-first. Each entry's date label
("August 11" — the year is implied by the page) becomes a right-panel
jump link; entries carry no tags because Mintlify replaces that jump
list with tag filters once any entry is tagged.
Content: all 29 entries from floxwebsite's changelog.yaml (Mar 2024 →
May 2026), merged by date with each feature as a ## heading so the RSS
feed keeps the old per-feature granularity, plus the May → Aug 2026 gap
(flox v1.12.1–v1.14.1 and flox-skills v1.0.0) written from the actual
release notes.
The {/* changelog-id: owner/repo@tag */} comments after each entry are
dedupe state for the release-stub automation (next commit); they sit
outside the Update bodies because Mintlify renders in-body MDX comments
as literal text in RSS feed items.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WN847FP3AM81Qg6J11uxoh
A daily scheduled workflow (08:00 UTC, sibling to the 06:00/07:00 update-flox-version and sync-man-pages jobs, same FloxBot token) polls the latest GitHub release of flox/flox, floxhub, floxenvs, flox-plugins, flox-skills, and flox-vscode, and opens a draft PR pre-filling an <Update> stub for a human to turn into real copy. Poll rather than push: only two of the six repos publish GitHub releases today, nothing in the org uses repository_dispatch, and a ≤24h detection delay disappears inside the editorial loop. Repos without releases no-op and light up automatically if they adopt releases later. Dedupe is stateless: the workflow greps the changelog pages for the release's changelog-id marker. Stub PR lifecycle: merge → never stubbed again; close unmerged → declined, a PR-exists guard stops recreation; leave open → daily runs skip it, so hand-written copy is never force-reset. scripts/changelog-stub.sh inserts stubs in date order (pages run newest-first, so out-of-order merges still land sorted) and routes by release year: current year → changelog.mdx; older years → the archive page, created and registered in docs.json if missing. A release dated after the current page's year instead triggers rollover as its own mechanical PR on a fixed branch (changelog-rollover-<year>): archive the page verbatim, register it, reset changelog.mdx. Concurrent new-year releases converge on one identical PR, an open rollover PR is refreshed from main daily so its archive snapshot never goes stale, and release stubs follow automatically after it merges. Archives are trusted by crash recovery only when complete (marker + matching title), writes are atomic, and unregistered archives heal on every run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WN847FP3AM81Qg6J11uxoh
djsauble
force-pushed
the
docs/changelog-migration
branch
from
August 18, 2026 01:24
9e00365 to
76d6def
Compare
tanjadev
approved these changes
Aug 18, 2026
tanjadev
left a comment
tanjadev
left a comment
Contributor
There was a problem hiding this comment.
Love the sidebar nav with the years!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Migrates flox.dev/changelog into the docs as a Changelog tab at
/docs/changelog, built on Mintlify<Update>components — per-entry anchors, product-tag filters, and a subscribable RSS feed at/docs/changelog/rss.xml.What's here
changelog.mdx— all 29 entries from floxwebsite'ssrc/data/changelog.yamlbackfilled (Mar 2024 → May 2026), merged by date with each feature as a##heading (Mintlify emits one RSS item per heading, so the feed keeps the old per-feature granularity) — plus the May → August gap: flox v1.12.1–v1.14.0 and flox-skills v1.0.0, generated through the stub pipeline below and then written up from the actual release notes.docs.json— a third nav tab, Changelog..github/workflows/changelog-stubs.yml— daily cron (08:00 UTC, after the 06:00/07:00 sibling jobs) that polls the latest GitHub release of flox/flox, floxhub, floxenvs, flox-plugins, flox-skills, and flox-vscode, and opens a FloxBot draft PR with a pre-filled<Update>stub for a human to turn into real copy. Repos without releases no-op; if one adopts releases later it lights up with no changes here.scripts/changelog-stub.sh— the stub generator (runs locally too). Inserts in date order so out-of-order merges keep the timeline sorted, and flags same-date collisions for the editor.How dedupe works (no state file)
Each published entry embeds
{/* changelog-id: owner/repo@tag */}; the workflow greps the page for it. Stub PR lifecycle:The second commit exercised this end-to-end: polling found exactly seven missing releases across the six repos, the script inserted them in scrambled order and produced correct reverse-chronological output, and all seven markers now dedupe — so the workflow's first scheduled run after merge should be a clean no-op, and the next real release (flox is due ~Aug 11 on its biweekly cadence) opens the first live draft PR.
After merge
Separate floxwebsite PR: 301
/changelog→/docs/changeloginpublic/netlify.toml, delete the old page + YAML, repoint nav links.Open calls flagged for review: product-tag taxonomy (
KubernetesandMCP servercover two backfill entries that fit no source repo), and the page stays indexable (Mintlify noindexes theirs).🤖 Generated with Claude Code
https://claude.ai/code/session_01WN847FP3AM81Qg6J11uxoh