IntersectMBO / IntersectMBO/lsm-tree

Publish a "snapshot version support" document

Open
#863 6 comments 0 reactions 0 assignees View on GitHub
documentation lsm-tree priority: high
Dominant language
Haskell
Stars
53
Forks
17
Avg merge
2d 3h
Merged PRs (30d)
4

Description

`lsm-tree` has a versioned on-disk format for snapshots. `lsm-tree` is backwards compatible with older snapshot versions. Forwards compatibility is not supported at all. `lsm-tree` committed to being backwards compatible with *at least* one snapshot version at all time, but it is not its goal to be backwards compatible indefinitely.

Users should have access to a document that describes `lsm-tree`'s procedure of adding new snapshot versions and dropping old snapshot versions. Moreover, the document should describe how users are affected by such snapshot version changes and how they should structure/modify their projects accordingly. Ideally the document would answer:

* How are users notified of new snapshot versions?
* For example: a major `lsm-tree` version bump and an entry in the changelog
* How should users structure their projects to account for future snapshot versions?
* For example: they should have tight enough bounds on `lsm-tree` versions so that all those `lsm-tree` versions produce the same snapshot version. Or, if they don't have such tight bounds, then they should implement a recovery strategy.
* How should users migrate from old snapshot versions to new ones?
* For example: open an old snapshot with a newer `lsm-tree` version, and then write it back to disk with the new format
* How are users notified of dropped old snapshot versions?
* @wenkokke suggested using a `MAJOR.MAJOR` package version bump to signal dropping support for older snapshot versions. For example, we could bump up from version `1.x` to `2.0`.
* how long should users expect versions to be supported?
* For example: at least a year?

Contributor guide

Open the contributing guide

Research direction

No file or test is named; start by reviewing the snapshot-version implementation and the changelog to identify the current compatibility and release procedures. Use the issue's questions to structure the document, resolving the proposed notification, migration, support-duration, and version-bump policies with maintainers. Done means the document explains both version changes and the actions users should take.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
databases, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.