doc: v2 to v3 migration guide #503
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a second CTA on the homepage, introduces a v2→v3 migration guide and tweaks an existing migration doc, defines structured ORM error types (class + enums), updates roadmap items, and extends REST/RPC API error docs to include DB error codes and typed error reasons. Changes
Sequence Diagram(s)(No sequence diagram provided — changes are documentation and small UI/markup edits without new runtime control-flow.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes
Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🪛 LanguageToolversioned_docs/version-3.x/migrate-v2.md[style] ~219-~219: Consider using a less common alternative to make your writing sound more unique and professional. (FEEL_FREE_TO_STYLE_ME) 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
versioned_docs/version-3.x/migrate-prisma.md(1 hunks)versioned_docs/version-3.x/migrate-v2.md(1 hunks)versioned_docs/version-3.x/roadmap.md(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- versioned_docs/version-3.x/migrate-prisma.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/migrate-v2.md
[style] ~183-~183: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...r that are planned to be removed in v3. Please feel free to share your thoughts about these decisio...
(FEEL_FREE_TO_STYLE_ME)
🔇 Additional comments (6)
versioned_docs/version-3.x/roadmap.md (1)
2-2: Roadmap updates align with v3 documentation expansion.The sidebar position reordering and TanStack Query integration status update are consistent with the broader migration guide introduction. Changes look good.
Also applies to: 13-13
versioned_docs/version-3.x/migrate-v2.md (5)
145-171: TanStack Query client API structure is well-documented.The migration example clearly shows the structural change from flat hook exports (
useFindManyUser) to schema-inferred client pattern (client.user.useFindMany). This aligns well with the roadmap completion status. Code examples are clear and practical.
43-116: Access policy migration section clearly outlines the plugin-based approach.The three-step pattern for policy migration (install package → declare plugin → install runtime) is well-structured. The v2 vs. v3 code comparison for post-update policies effectively illustrates the breaking change from
future().ownerIdtobefore().ownerIdsemantics. Examples are helpful.
39-41: Verify Prisma migration guide completeness.Line 41 references a separate Prisma Migration Guide at
./migrate-prisma.md. Ensure this guide covers the essential migration steps comprehensively, particularly database schema compatibility and feature gaps mentioned in line 33.The migration guide refers to
./migrate-prisma.mdfor detailed Prisma migration instructions. Please confirm that this referenced file exists and contains complete migration guidance for replacing Prisma dependencies with ZenStack ORM.
118-143: Server adapter migration example requires API signature verification.The code example shows
RPCApiHandlerandZenStackMiddlewareusage patterns. Verify that constructor signatures and method names (apiHandler,getClient) match the current implementation, particularly the renaming fromgetPrismatogetClient.
1-220: I need to verify a few more details about the documentation structure and API references:Let me check for the orm/plugins directory and verify the plugin references:
Let me search the codebase for the orm/plugins directory structure and verify the plugin references:
All internal documentation links are valid and API signatures match implementation.
The verification confirms:
- All referenced documentation files exist in the versioned_docs/version-3.x/ directory (
migrate-prisma.md,orm/access-control/post-update.md,service/server-adapter.md,modeling/plugin.md)- check-permission.md and openapi.mdx files are present in the docs/ directory structure
- The API signatures in the examples match v3 implementation patterns (e.g.,
AccessControlPluginfrom@zenstackhq/runtime), and the migration guide's reference toPolicyPluginfrom@zenstackhq/plugin-policyis appropriate for the v2-to-v3 migration context- The code examples showing
ZenStackClient,$use(), and$setAuth()methods are consistent with v3 API patterns- The orm/plugins/ reference refers to the documentation category containing plugin documentation pages
No corrections needed to the migration guide content.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
versioned_docs/version-3.x/migrate-v2.md (2)
29-29: Resolve the unaddressed grammar error from prior review.This issue was flagged in the previous review and remains unresolved. The phrase "only native the traditional TCP-based connection" contains a redundant descriptor.
- For PostgreSQL, only native the traditional TCP-based connection is supported. Newer HTTP-based protocols, such as those supported by providers like Neon and Prisma PG, are not yet supported, but will be in the future. + For PostgreSQL, only the traditional TCP-based connection is supported. Newer HTTP-based protocols, such as those supported by providers like Neon and Prisma PG, are not yet supported, but will be in the future.
219-219: Resolve the unaddressed style issue from prior review.This issue was flagged in the previous review and remains unresolved. The phrasing "Please feel free to share your thoughts" is too informal for technical documentation.
-This section lists v2 features that haven't been migrated to v3 yet, or that are planned to be removed in v3. Please feel free to share your thoughts about these decisions in [Discord](https://discord.gg/Ykhr738dUe), and we'll be happy to discuss them. +This section lists v2 features that haven't been migrated to v3 yet, or that are planned to be removed in v3. We welcome feedback on these decisions in [Discord](https://discord.gg/Ykhr738dUe).
🧹 Nitpick comments (1)
versioned_docs/version-3.x/migrate-v2.md (1)
91-91: Clarify the before() function reference.Line 91 mentions "you can use the
before()function to refer to the 'before-update' state" but provides no signature or detailed documentation link. Consider linking to the post-update policy documentation for completeness.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
versioned_docs/version-3.x/migrate-v2.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/migrate-v2.md
[style] ~219-~219: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...r that are planned to be removed in v3. Please feel free to share your thoughts about these decisio...
(FEEL_FREE_TO_STYLE_ME)
🔇 Additional comments (1)
versioned_docs/version-3.x/migrate-v2.md (1)
66-89: Verify plugin initialization pattern is correct.The code example at line 66–89 shows
$use()and$setAuth()methods. Please confirm these match the actual v3 API and are not placeholders.
Summary by CodeRabbit
New Features
Documentation