Skip to content

[P3][docs] Add a migration and downgrade guide (docs/MIGRATION.md) #59

Description

@cevheri

Summary

Roadmap item (suggested in the PR #43 external review, Kimi round; deferred at the time because the changeset and RELIABILITY.md carry the warning). Collect the version-migration facts into one discoverable document instead of leaving them spread across the CHANGELOG entry and RELIABILITY.md.

Content

  • The v0.1.x -> v0.2.0 on-disk story: headerless legacy files open transparently and keep legacy framing on appends; new files carry the LRDB v1 header.
  • THE DOWNGRADE WARNING, prominently: a v1 file opened by <= 0.1.3 is silently truncated to zero — back up before any downgrade. (Today this lives in the CHANGELOG and RELIABILITY.md; a user searching "downgrade" should land here.)
  • The two legacy behavior changes: a headerless file whose only record is torn now refuses as NOT_A_DATABASE (0.1.3 opened it as empty); files shorter than 8 bytes are refused untouched.
  • How to convert a legacy file to v1 deliberately (today: export/reimport or copy through a fresh database; becomes nicer once doctor [P3][cli] Add a libredb doctor command for non-mutating file diagnosis #51 and an export command exist — cross-link).
  • The format compatibility policy going forward (feeds the production-arc issue).

Constraints

  • Docs only; no changeset. English, no emoji, honest voice.
  • Link from README (Documentation table), RELIABILITY.md, and the CLI backup section.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docsPre-announcement auditenhancementNew feature or requestpriority/lowPre-announcement audit

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions