ENG-1519: Add legacy-to-blockprops migration, remove backedBy from schemea by sid597 · Pull Request #876 · DiscourseGraphs/discourse-graph

sid597 · 2026-03-10T09:14:22Z

https://www.loom.com/share/f7367e084c2e424eb20e31fdfd937d14

Summary by CodeRabbit

Chores
- Implemented legacy settings migration system to transfer existing settings to block properties format.
- Added support for migrating feature flags, global settings, and personal settings with progress tracking.
- Updated node configuration to align with new settings storage structure.

…hema

linear · 2026-03-10T09:14:24Z

ENG-1519 Initial one time load/migration of blocks to block props

supabase · 2026-03-10T09:14:27Z

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

sid597 · 2026-03-10T09:14:38Z

@coderabbitai full review

coderabbitai · 2026-03-10T09:14:51Z

✅ Actions performed

Full review triggered.

coderabbitai · 2026-03-10T09:26:37Z

📝 Walkthrough

Walkthrough

The PR removes the backedBy field from discourse node schema and introduces migration utilities to convert legacy settings into block properties. New functions enable reading legacy feature flags, global, personal, and discourse node settings. Migration functions handle transformation and persistence of these settings during initialization.

Changes

Cohort / File(s)	Summary
Schema Changes `apps/roam/src/components/settings/utils/zodSchema.ts`, `apps/roam/src/components/settings/utils/zodSchema.example.ts`	Removed `backedBy` optional field from DiscourseNodeSchema, eliminating the property from the public schema and derived DiscourseNodeSettings type.
Legacy Settings Readers `apps/roam/src/components/settings/utils/accessors.ts`	Added four new utility functions: `readAllLegacyFeatureFlags()`, `readAllLegacyGlobalSettings()`, `readAllLegacyPersonalSettings()`, and `readAllLegacyDiscourseNodeSettings()` to aggregate legacy settings by iterating over keys and invoking corresponding legacy getters.
Migration Orchestration `apps/roam/src/components/settings/utils/migrateLegacyToBlockProps.ts`	New module implementing `migrateGraphLevel()` and `migratePersonalSettings()` that validate legacy data against schemas, compare against defaults, write to block properties when needed, and track migration status via marker blocks.
Initialization `apps/roam/src/components/settings/utils/init.ts`	Added calls to `migrateGraphLevel(blockUids)` before and `migratePersonalSettings(blockUids)` after discourse node page initialization in `initSchema`.
Node Creation `apps/roam/src/components/settings/DiscourseNodeConfigPanel.tsx`	Removed `backedBy: "user"` property from object passed to `DiscourseNodeSchema.parse()` during node creation.

Sequence Diagram

sequenceDiagram
    participant Init as Initialization
    participant LegacyReader as Legacy Settings Reader
    participant Validator as Schema Validator
    participant BlockProps as Block Properties Writer
    participant Storage as Marker Storage

    Init->>Init: Start initSchema
    Init->>LegacyReader: Call migrateGraphLevel()
    LegacyReader->>LegacyReader: Read legacy feature flags, global, & discourse node settings
    LegacyReader->>Validator: Validate against FeatureFlagsSchema, GlobalSettingsSchema, etc.
    Validator->>Validator: Compare against defaults & existing props
    Validator->>BlockProps: Write block properties if needed
    BlockProps->>Storage: Write migration marker block on success
    Storage-->>Init: Migration complete
    Init->>LegacyReader: Call migratePersonalSettings()
    LegacyReader->>LegacyReader: Read personal settings
    Validator->>BlockProps: Write personal settings to block props
    BlockProps->>Storage: Set personal settings marker
    Storage-->>Init: Personal migration complete
    Init->>Init: Initialize discourse node pages

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

ENG-1189: Prod: Init block prop based schema #666: Introduces initSchema function that the main PR modifies to add migration calls during initialization.
ENG-1105: zod schema for all the settings #664: Originally introduced the backedBy field in DiscourseNodeSchema that this PR removes.
ENG-1479: Port suggestive mode settings to dual-read #845: Adds legacy feature flag dual-read utilities in accessors, directly related to the new readAllLegacyFeatureFlags() function.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the two main changes: adding legacy-to-blockprops migration and removing backedBy from schema, matching the primary objectives of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

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.}

…al block

sid597 · 2026-03-10T19:01:17Z

apps/roam/src/components/settings/utils/zodSchema.ts

    .optional()
    .transform((val) => val ?? defaultNodeIndex()),
  suggestiveRules: SuggestiveRulesSchema.default({}),
-  backedBy: z


We do not need to have the backedBy in the schema, in the legacy settings we set the backedBy at the runtime, we do not save it anywhere in the blocks

sid597 · 2026-03-10T19:14:55Z

apps/roam/src/components/settings/utils/migrateLegacyToBlockProps.ts

+export const migratePersonalSettings = async (
+  blockUids: Record<string, string>,
+): Promise<void> => {
+  if (getSetting<boolean>(PERSONAL_MIGRATION_MARKER, false)) {


Personal settings is per user so we check if this user's personal settings have migrated or not, it could be the case that all the global and discourse node settings have migrated but not the user's personal settings

sid597 · 2026-03-10T20:11:28Z

apps/roam/src/components/settings/utils/init.ts


 export const initSchema = async (): Promise<InitSchemaResult> => {
  const blockUids = await initSettingsPageBlocks();
+  await migrateGraphLevel(blockUids);


This runs before initDiscourseNodePages() on purpose. The init check for “do we already have user discourse nodes?” only looks at block props, so legacy node pages without migrated props would be invisible there and the graph could be mistaken for an empty graph. Running migration first makes those existing legacy node pages visible to the new-store check before default node seeding happens.

…cy-to-blockprops-migration

sid597 · 2026-03-11T11:48:29Z

apps/roam/src/components/settings/utils/accessors.ts

 };

-// Reconstructs global settings from getFormattedConfigTree() shape to match block-props schema shape
+// Reconstructs global settings from legacy Roam tree to match block-props schema shape


Moving away from getFormattedConfigTree()

mdroidian

Approved. One small change from backend to async for the query.

I also added a few additional devin comments, let's take a second to review/resolve them before merging 👍

apps/roam/src/components/settings/utils/accessors.ts

apps/roam/src/components/settings/utils/migrateLegacyToBlockProps.ts

ENG-1519: Add legacy-to-blockprops migration, remove backedBy from sc…

cd16a66

…hema

This comment was marked as resolved.

Sign in to view

Fix shouldWrite skipping after reconciliation, warn on missing person…

b97def3

…al block

sid597 commented Mar 10, 2026

View reviewed changes

Add migration telemetry for legacy parse failures

14e72c9

sid597 commented Mar 10, 2026

View reviewed changes

Use backend query for node migration

def877f

sid597 requested a review from mdroidian March 11, 2026 09:33

Merge branch 'migration-block-init-staging-branch' into eng-1519-lega…

29f99fc

…cy-to-blockprops-migration

sid597 commented Mar 11, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

mdroidian approved these changes Mar 11, 2026

View reviewed changes

apps/roam/src/components/settings/utils/accessors.ts Show resolved Hide resolved

apps/roam/src/components/settings/utils/migrateLegacyToBlockProps.ts Outdated Show resolved Hide resolved

fix review

f62b3f8

sid597 merged commit a1f1dc0 into migration-block-init-staging-branch Mar 13, 2026
8 checks passed

Conversation

sid597 commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

linear bot commented Mar 10, 2026

Uh oh!

supabase bot commented Mar 10, 2026

Uh oh!

sid597 commented Mar 10, 2026

Uh oh!

coderabbitai bot commented Mar 10, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

coderabbitai bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Uh oh!

This comment was marked as resolved.

Uh oh!

sid597 Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

sid597 Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

sid597 Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

sid597 Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

mdroidian left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sid597 commented Mar 10, 2026 •

edited

Loading

coderabbitai bot commented Mar 10, 2026 •

edited

Loading