docs: record the v0.20.33 release traps - #830
Conversation
Four lessons from cutting v0.20.33, which took four candidates. Two were real
defects that would have shipped an SDK where TTS does not link.
The expensive one: a new NeuRT archive must be added in FOUR places, and three
only fail in a build configuration a dev Mac never produces. Miss the force-load
lists and every native job is green while validate_consumer_flutter dies an hour
later on `Undefined symbol: _g_neurt_tts_ops` -- the engine registers, all CMake
targets compile, only a CONSUMER's link fails. Miss the `#if RAC_NEURT_ROUTABLE`
guard on the vtable entry and the opposite happens: routable builds are fine and
every PR job without NEURUN_TOKEN fails, because the non-routable shell still
references a symbol nothing defines. A machine with the payload staged is
routable and reproduces neither.
This file already notes that prose alone did not stop the checksum-staleness bug
recurring twice, so the archive-list half now has a mechanism:
`neurt_assert_no_unlisted_archives` fails packaging by name. The vtable guard has
none -- hence the instruction to audit all ten slots, and the note that moving
core/third_party/neurt aside reproduces a non-routable build in one step.
Also recorded: reuse_native_web_run_id is same-version-only (the wasm embeds
RAC_VERSION_STRING, and a skipped native_web leaves the candidate unusable for
publish_from_run_id); checksum verification must match by NAME as well as URL,
because a URL-only cross-check validates 9 of 15 sites and reports success; and
`rcli backends --json` against the OSS kit lists no neurt at all, so a
routability check there passes cleanly and proves nothing.
check_agents_claude_sync.sh All 19 CLAUDE.md -> AGENTS.md symlinks present
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R6p1R4pwTg5pvVjiEjq9ZA
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review. 📝 WalkthroughWalkthroughChangesRelease pipeline lessons
Estimated code review effort: 1 (Trivial) | ~2 minutes Merge Risk: ⚪ Minimal · up to This change only records release-process lessons in repository documentation and does not alter product or runtime behavior; no actionable merge-blocking risk remains beyond normal checks and review. Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Description checkExplanation The description gives a detailed and relevant account of the four release lessons, but it does not follow the repository template. It omits the required Description, Type of Change, Testing, Labels, Checklist, and Screenshots sections. Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
Four lessons from cutting v0.20.33, which took four candidates. Two of those were real
defects that would have shipped an SDK where TTS does not link.
The expensive one: a new NeuRT archive lands in FOUR places
Three of them only fail in a build configuration a dev Mac never produces:
build-core-xcframework.shhas two — a pre-flight guard and_NEURT_ROUTABLE_ARCHIVES— pluspackage-private-engine-overlay.sh) and every native jobgoes green while
validate_consumer_flutterdies an hour later onUndefined symbol: _g_neurt_tts_ops. The engine registers, all CMake targets compile, andonly a consumer's link fails.
#if RAC_NEURT_ROUTABLEguard on the vtable entry and the opposite happens:routable builds are fine, and every PR job without
NEURUN_TOKENfails, because thenon-routable shell still references a symbol nothing defines.
A machine with the payload staged is routable, so it reproduces neither.
This file already records that prose alone did not stop the checksum-staleness bug recurring
twice — so the archive-list half now has a mechanism:
neurt_assert_no_unlisted_archivesfails packaging by name and points at all three files. The vtable guard has none, hence the
instruction to audit all ten slots, and the note that moving
core/third_party/neurtasidereproduces a non-routable build in one step.
Three more
reuse_native_web_run_idis same-version-only.racommons.wasmembedsRAC_VERSION_STRING. Worse than the red job:native_webis skipped, so that candidatenever uploads a web artifact and can never serve as
publish_from_run_id.\(sdkVersion); the Flutter ones bind a checksum to aname:through a helper with no URLat the call site. A URL-only cross-check validates 9 of 15 sites and reports success.
rcli backends --jsonagainst the OSS kit proves nothing. NeuRT ships as a separateprivate pack, so the public bottle lists no
neurtat all — the check passes cleanly andmeans nothing.
🤖 Generated with Claude Code
https://claude.ai/code/session_01R6p1R4pwTg5pvVjiEjq9ZA
Summary by CodeRabbit