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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

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

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions