Skip to content

docs(migrating): restructure migrating section for further consolidation#10451

Open
BlueCutOfficial wants to merge 1 commit intowarp-drive-data:mainfrom
BlueCutOfficial:docs-move-migration-intro
Open

docs(migrating): restructure migrating section for further consolidation#10451
BlueCutOfficial wants to merge 1 commit intowarp-drive-data:mainfrom
BlueCutOfficial:docs-move-migration-intro

Conversation

@BlueCutOfficial
Copy link
Copy Markdown
Contributor

This PR proposes restructuring the information on migrating from Model to Schema, to make it easier to find and potentially open up more migration paths.

Motivation:

  • If I have an Ember app using EmberData models, and I want to start using schemas, then it is legitimate to look into the Migrating section first. However, for the moment, pieces of information are spread between different sections related to LegacyMode, and it's a bit hard to put all the pieces of the puzzle together.
  • "Two Store Migration" and "V4 to V5 Migration" are two separate documents, but the latter implies the former: when going through the V4 to V5 migration steps, the reader is asked to install the mirror packages and create a v2-store file. However, if V4 to V5 is the first document I look at, then the two-store concept is not introduced, and I don't fully understand what I am doing.
  • With @warp-drive/legacy, it is now possible to have models and schemas coexisting using only one legacy store. The mirror approach seems overly complicated to enable having schemas in the simpler scenarios. The migrating guide should probably provide this more straightforward migration path.

1st Iteration Suggestion:

  • Don't say too much about migration things in sections that are not dedicated to the migration: most of the content of Manual/Schemas/Resources/LegacyMode ## Migration is moved as the introduction of the Migrating section.
  • The Migrating section now has this introduction that clarifies a bit the scenarios: we are talking about migrating from Models to Schemas, this is the place where the readers learn that they are not left behind when they are stuck on Ember 3 or 4, then the migration options are introduced.
  • Create a section for the Two Store approach that contains the same documents we had before: concept and cookbook, so it makes clear the cookbook (as it is now) follows the Two Store approach.

This structure lays the groundwork for more iterations on the migrating section: we could more easily add a new doc for a migration path that simply changes the existing store to be a WarpDrive legacy store, extract shared prerequisites from the existing 2-store-based cookbook to simplify it (and potentially re-merge it with the concept doc and avoid a sub-section), etc.

@runspired
Copy link
Copy Markdown
Contributor

With @warp-drive/legacy, it is now possible to have models and schemas coexisting using only one legacy store. The mirror approach seems overly complicated to enable having schemas in the simpler scenarios. The migrating guide should probably provide this more straightforward migration path.

This is going to really depend on the app. My impression is that most of the apps that haven't made the jump from 4.x to 5.x haven't done so because they are stuck due to deprecations such as those for array-like and promise-proxies or are using model fragments.

Any app stuck due to deprecations is going to have an easier time migrating using the two-store approach, while any app that already made the jump can just intermix models and schemas during the migration.

When the two-store approach doc was originally written, it was just one of several distinct migration paths possible: the point being to provide app's flexibility in how to migrate depending on their specific circumstances - what we need to do better is describe when each approach is best.

@BlueCutOfficial
Copy link
Copy Markdown
Contributor Author

BlueCutOfficial commented Jan 16, 2026

The point you are making is 100% compatible with the changes I am suggesting for the Migrating doc IMO.

any app that already made the jump can just intermix models and schemas during the migration

Right, but this migration is not explicitly documented in the Migrating guide. Developers have to make their way with all the existing guides (setup, manual sections, legacy-mode-related content...), without being confused by a migrating guide that is called "migrating" but actually doesn't match their migration scenario. I first tried to move from EmberData to WarpDrive with a 6.9 app building with Vite, and it was not easy for me to figure out the right path.

what we need to do better is describe when each approach is best.

I totally agree with this 👍 and I think a good place for this is the migrating/index.md that I introduce in this PR.

I designed this PR as a first iteration that simply moves the information to leave room for more improvements for the Migrating guides. I didn't want to write new content in this PR to keep the structure concern and the content concern separate, and keep each piece reviewable and mergeable; but I am happy to draft the next steps I imagine for the guides if that can make this one clearer, or at least make the bullet points in the introduction a bit more explicit.

@BlueCutOfficial BlueCutOfficial force-pushed the docs-move-migration-intro branch from b28b89d to fd0b4dd Compare January 16, 2026 15:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants