docs: add 0.4-to-0.5 migration guide (#106) by JasonCust · Pull Request #125 · CentralPing/centralping.github.io

JasonCust · 2026-06-12T03:39:29Z

Summary

Create 0.4-to-0.5.mdx migration guide covering ergo 0.5.0 and ergo-router 0.5.0 changes: potentially breaking registration-time config validation (body: false + validate.body), notable additions (validate shorthand, responseSchema, onResponse, catchHandler 4th argument, new presets), informational items (multi-runtime CI, @types/node optional peer dep), and cumulative changes
Update 0.3-to-0.4.mdx cumulative section with two ergo 0.2.0 breaking changes previously omitted (validate no-body 500, idempotency malformed header 400)
Update migration cross-links in ergo.mdx, ergo-router.mdx, and getting-started.mdx to point to /migration/0.4-to-0.5/

Closes #106

- Create 0.4-to-0.5.mdx covering ergo 0.5.0 and ergo-router 0.5.0: potentially breaking registration-time config validation, notable additions (validate shorthand, responseSchema, onResponse, catchHandler 4th arg, new presets), informational items, and cumulative changes - Update 0.3-to-0.4.mdx cumulative section with two missing ergo 0.2.0 breaking changes (validate no-body, idempotency malformed header) - Update cross-links in ergo.mdx, ergo-router.mdx, and getting-started.mdx to point to /migration/0.4-to-0.5/

coderabbitai · 2026-06-12T03:39:36Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 447e0ed4-bd5e-43d9-86e7-ab435b002303

📥 Commits

Reviewing files that changed from the base of the PR and between e2d9b30 and 032ebc9.

📒 Files selected for processing (5)

src/content/docs/getting-started.mdx
src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/migration/0.4-to-0.5.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/packages/ergo.mdx

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (3)

src/content/**/*

📄 CodeRabbit inference engine (Custom checks)

src/content/**/*: API descriptions, function signatures, and option defaults in src/content/ must match the current state of ergo or ergo-router source code and JSDoc
RFC citations in src/content/ must reference correct section numbers and current RFC versions (not outdated versions)
Code examples in src/content/ must not use deprecated API patterns or incorrect import paths

Files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

**/*

📄 CodeRabbit inference engine (Custom checks)

Do not introduce TODO, FIXME, HACK, or XXX comments in newly added lines of code

Files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

src/content/**

⚙️ CodeRabbit configuration file

src/content/**: Documentation content (MDX). Verify technical accuracy of ergo/ergo-router API descriptions, correct RFC references, and consistent terminology with the library READMEs and JSDoc. Code examples must match current API signatures. Dual JS/TS examples use Starlight Tabs/TabItem components.

Files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

🧠 Learnings (3)

📚 Learning: 2026-06-05T06:06:10.155Z

Learnt from: JasonCust
Repo: CentralPing/centralping.github.io PR: 46
File: src/content/docs/recipes/mixed-auth-cors-csrf.mdx:53-65
Timestamp: 2026-06-05T06:06:10.155Z
Learning: When reviewing docs that show `createRouter({ transport: { cors: { ... } } })`, use the ergo-router transport CORS schema (e.g., `origin` as a string or pattern, `credentials` boolean, and `allowedHeaders` array). Do not confuse it with the ergo standalone CORS schema from `ergo/http/cors.js` (`origins`, `allowCredentials`, `allowHeaders`). The transport layer renames/destructures its own properties before calling the shared validator, so the docs should reflect the transport-layer option names.

Applied to files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

📚 Learning: 2026-06-06T22:00:49.387Z

Learnt from: JasonCust
Repo: CentralPing/centralping.github.io PR: 70
File: src/content/docs/middleware/json-api-query.mdx:46-47
Timestamp: 2026-06-06T22:00:49.387Z
Learning: When reviewing CentralPing’s docs for the `centralping/ergo` middleware/router pipeline architecture, do not treat the `accumulator.mdx` “middleware internal config key → setPath mapping” table as requiring that *all* middleware be wrapped in `{fn, setPath}` in standalone `compose()` examples. `pipeline-builder.js` middleware entries in `accumulator.mdx` list `setPath` mappings (including validation gates like `jsonApiQuery` and `validate`), but standalone `compose()` examples should use bare function middleware for validation gates and response-only middleware (e.g., `jsonApiQuery()`, `validate()`, `securityHeaders()`, `cacheControl()`), per the docs’ “Response-only middleware are plain functions — no wrapper needed” note. Therefore, don’t flag `accumulator.mdx` vs standalone `compose()` examples as an inconsistency.

Applied to files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

📚 Learning: 2026-06-07T15:55:55.620Z

Learnt from: JasonCust
Repo: CentralPing/centralping.github.io PR: 87
File: src/content/docs/getting-started.mdx:203-205
Timestamp: 2026-06-07T15:55:55.620Z
Learning: In the docs (including `src/content/docs/getting-started.mdx` and the other ergo-router-related MDX pages), clearly distinguish router-seeded data from middleware-accumulated data in the domain accumulator:
- Router-seeded: `acc.route.params` is seeded by the router before the pipeline runs (e.g., via `auto-wrap.js` creating `accumulator({ route: { params } })`), so it is not produced by middleware.
- Middleware-accumulated: values like `acc.body`, `acc.auth`, etc. are produced/accumulated by middleware during the pipeline.
Documentation should use this distinction consistently when describing where `acc` fields come from.

Applied to files:

src/content/docs/migration/0.3-to-0.4.mdx
src/content/docs/getting-started.mdx
src/content/docs/packages/ergo.mdx
src/content/docs/packages/ergo-router.mdx
src/content/docs/migration/0.4-to-0.5.mdx

🔇 Additional comments (15)

src/content/docs/getting-started.mdx (1)

315-316: LGTM!

src/content/docs/packages/ergo-router.mdx (1)

949-949: LGTM!

src/content/docs/packages/ergo.mdx (1)

71-71: LGTM!

src/content/docs/migration/0.4-to-0.5.mdx (10)

1-29: LGTM!

30-89: LGTM!

90-126: LGTM!

127-160: LGTM!

161-192: LGTM!

193-218: LGTM!

219-244: LGTM!

245-263: LGTM!

264-293: LGTM!

294-309: LGTM!

src/content/docs/migration/0.3-to-0.4.mdx (2)

169-178: LGTM!

180-189: LGTM!

Summary by CodeRabbit

Documentation
- Added comprehensive migration guide for upgrading from version 0.4.x to 0.5.x, covering breaking changes and new features including validate shortcuts, response schema projection, onResponse lifecycle hooks, and new router presets.
- Updated documentation links to point to the latest migration guide.
- Enhanced earlier migration guide with additional breaking-change notes for users upgrading from versions prior to 0.3.x.

Walkthrough

This PR releases the 0.4→0.5 migration guide and updates documentation navigation. A new comprehensive MDX guide documents the potentially breaking body validation registration-time check, non-breaking additions (validate shorthand, responseSchema, onResponse hook, new router presets), and cumulative breaking changes from earlier versions. The 0.3→0.4 guide is backfilled with 0.2.0 breaking-change notes. Navigation links across four docs are updated to point to the new 0.4→0.5 guide.

Changes

Migration guides for 0.4→0.5 release

Layer / File(s)	Summary
New 0.4→0.5 migration guide `src/content/docs/migration/0.4-to-0.5.mdx`	Comprehensive guide for upgrading from 0.4.x to 0.5.x, documenting the potentially breaking change (body:false + validate.body now throws at registration time), before/after migration examples, non-breaking additions (validate shorthand JSON-schema detection, responseSchema projection, onResponse lifecycle hook, catchHandler 4th argument with domainAcc, three new ergo-router presets: sse, webhooks, public), multi-runtime CI support (Deno/Bun), optional `@types/node` peer dependency, cumulative breaking changes from earlier versions, and post-migration verification checklist.
Cumulative breaking changes in 0.3→0.4 guide `src/content/docs/migration/0.3-to-0.4.mdx`	Adds "From 0.1.x" sections documenting ergo 0.2.0 breaking changes: validate body ordering (`body()` middleware prerequisite producing 500 + ERGO_VALIDATE_NO_BODY warning) and idempotency header malformed vs missing distinction (400 format guidance regardless of `required` option) for users upgrading across multiple versions.
Update navigation links to latest guide `src/content/docs/getting-started.mdx`, `src/content/docs/packages/ergo.mdx`, `src/content/docs/packages/ergo-router.mdx`	Updates "Migration Guides" hyperlink targets from `/migration/0.3-to-0.4/` to `/migration/0.4-to-0.5/` across Getting Started, ergo package, and ergo-router package documentation pages.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

CentralPing/centralping.github.io#98: Established the 0.3→0.4 migration guide template; this PR adds the 0.4→0.5 successor guide and updates the same navigation links.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows the conventional commit format with correct type (docs), lowercase imperative description, and issue number reference.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding-related objectives from issue `#106` including the 0.5.0 migration guide with breaking changes, new features, code examples, cumulative changes documentation, and cross-linking.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the migration guide objectives: the new 0.4-to-0.5 guide, cumulative breaking changes in 0.3-to-0.4, and updated navigation links across documentation.
Content Accuracy	✅ Passed	Changed MDX links and migration content match existing repo API docs (validate shorthand, ERGO_VALIDATE_NO_BODY + 500, idempotency RFC8941 400, body:false+validate.body registration-time throw, onR...
Zero Tech Debt	✅ Passed	Scanned the changed docs files for TODO/FIXME/HACK/XXX in the repository and found no matches.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

Review ran into problems

🔥 Problems

Linked repositories: Your configuration references 2 linked repositories, but your current plan allows 0. Analyzed ``, skipped CentralPing/ergo, `CentralPing/ergo-router`.

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

JasonCust · 2026-06-12T04:10:05Z

@coderabbitai full review

coderabbitai · 2026-06-12T04:10:11Z

✅ Action performed

Full review finished.

JasonCust

Lead Architect Review

Verdict: APPROVE

(Posted as COMMENT because GitHub disallows self-approval — the review verdict is APPROVE.)

Clean documentation PR — the 0.4-to-0.5 migration guide accurately reflects the ergo 0.5.0 and ergo-router [Unreleased] changelogs, all cross-links resolve to valid pages, cumulative entries are verified against ergo CHANGELOG 0.2.0 source, and the backfilled entries in 0.3-to-0.4 close a real documentation gap. CI build passes.

Blocking items: 0
Non-blocking items: 0

JasonCust self-assigned this Jun 12, 2026

coderabbitai Bot approved these changes Jun 12, 2026

View reviewed changes

JasonCust commented Jun 12, 2026

View reviewed changes

JasonCust merged commit 4f525eb into main Jun 12, 2026
3 checks passed

JasonCust deleted the docs/migration-guide-0.5-106 branch June 12, 2026 04:28

coderabbitai Bot mentioned this pull request Jun 17, 2026

docs: normalize code style to match library Prettier config (#140) #162

Merged

Navigation Menu

Repository navigation

docs: add 0.4-to-0.5 migration guide (#106) - #125

docs: add 0.4-to-0.5 migration guide (#106)#125
JasonCust merged 1 commit into
mainfrom
docs/migration-guide-0.5-106

JasonCust commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading

Review ran into problems

Uh oh!

JasonCust commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

JasonCust left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

JasonCust commented Jun 12, 2026

Summary

Uh oh!

coderabbitai Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Review ran into problems

Uh oh!

JasonCust commented Jun 12, 2026

Uh oh!

coderabbitai Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JasonCust left a comment

Choose a reason for hiding this comment

Lead Architect Review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading