Skip to content

[did2 #14] Migration guide (user-facing docs) #787

@stevevanhooser

Description

@stevevanhooser

Part of the NDI-matlab did2 migration. Target branch: Vnext.

Scope

One-page user-facing migration guide explaining what changed, how to upgrade, and what breaks.

Suggested location: docs/MIGRATION_TO_V_DELTA.md (or whichever docs/ convention the repo uses).

Contents:

  • What V_delta is and why we're migrating (link to did-schema/schemas/V_delta_SPEC.md).
  • What stays the same: the doc.document_properties.<class>.<field> accessor pattern, ndi.query signature, ndi.database API, base.* field names.
  • What breaks (the small list):
    • The four collapsed-ontology classes: probe_location, treatment, ontology_image, ontology_label. Show before/after snippets for each.
    • depends_on(k).iddepends_on(k).value (mitigated by compat; document the canonical V_delta form).
    • Removal of document_properties.ndi_document.* (long-deprecated; document the move to base.*).
    • Removal of document_class.superclasses[i].definition (internal plumbing; affects any user code that read it directly).
  • How to migrate:
    • Local: ndi.migrate.local(path).
    • Cloud: ndi.migrate.cloud(datasetId) — including the publish-state flow and the ForceUnpublish flag.
  • Deprecation timeline (see issue 15).

Out of scope

API reference docs. This is a guide, not a manual.

Dependencies

Rough draft can start after issue 5 (alias table makes the "what changed" list concrete). Finalize after issue 10 (so usage examples are accurate).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions