Repository navigation
docs(upgrade): no migration notes for 0.1.1, 0.1.2, or 0.1.3 (only the 0.1.0 page exists) #4398
Description
The docs/upgrade/ directory contains only 0-1-0.mdx. Three GA releases have shipped since (0.1.1, 0.1.2, 0.1.3) with no upgrade or migration page for any of them. A reader running 0.1.1 or later has no way to tell whether the 0.1.0 guidance still applies or what changed in their jump.
This matters most for 0.1.3, which is not a pure patch release. From the release notes it includes operator-affecting changes with no migration guidance:
feat(helm): make cluster-scoped RBAC optional(feat(helm): make cluster-scoped RBAC optional #3459) — changes the RBAC an operator installs.fix(network): refuse protocol upgrades on JSON-RPC and MCP endpoints(fix(network): refuse protocol upgrades on JSON-RPC and MCP endpoints #3753) and the GraphQL equivalent (fix(network): refuse protocol upgrades on GraphQL endpoints #3841) — can break clients that relied on protocol upgrades.feat(sandbox): add main restart policy(feat(sandbox): add main restart policy #2798) — changes sandbox restart behavior.
By contrast, 0.1.1 and 0.1.2 look like patch releases (fixes, docs, perf), with only minor behavior changes in 0.1.1 (WebSocket tunnel made opt-in, snap gateway mTLS). If that is correct, even a one-line "no migration steps beyond 0.1.0" note would close the gap for those two.
Request
- Add upgrade notes for 0.1.1, 0.1.2, and 0.1.3, even where the entry is simply "no action needed," and state which parts of the 0.1.0 guide still apply.
- To prevent recurrence, consider making an "upgrade impact / migration steps" entry a standard part of the release checklist, so each release either links a
docs/upgrade/page or explicitly records that no migration is required. You already publish detailed GitHub release notes (see docs: describe 0.1 series in release callouts #3732); this would add a short upgrade-impact callout rather than a new process.
Found while writing operator upgrade guidance for a downstream consumer (Red Hat Agentic Starter Kits guide) pinned at 0.1.2.
Activity
matthewgrossman commentedon Oct 13, 2026
#4497 needs info on an upgrade guide. I opened a draft PR, #4520, that adds an example
docs/upgrade/0-1-5.mdxusing #4497 as its only entry. It's meant as a concrete starting point for settling the process here: one page per release or a running page, and who writes each entry.fix(openclaw): update to OpenClaw 2026.9.8 and OpenShell 0.1.2 (#373)
matthewgrossman commentedon Oct 20, 2026
hey @rhuss , the recent 0.1.5 release has an upgrade section that is sourced from PR descriptions and AI-assisted. You think that solves your concern here?
rhuss commentedon Oct 26, 2026
Thanks @matthewgrossman. I looked at
release-notes.ymlfrom #4654, and yes, it solves this going forward. A fixed Upgrade notes section, with PR Release Notes as the source, is what I was asking for, and the 0.1.5 notes read well. I'll skip backfilling 0.1.1 to 0.1.3; anyone on those versions is better served by the latest notes.One small follow-up:
docs/upgrade/still has only the 0.1.0 page, so people reading the docs won't find these notes. A single page linking each release's Upgrade notes would be enough. I'm happy to send a PR for that, plus a hint in the PR template's Release Notes section asking authors to state required upgrade actions. Otherwise, feel free to close this.