Skip to content

Version the save-file format and add compatibility coverage #5

@JakenHerman

Description

@JakenHerman

Summary

The save-file JSON structure is not explicitly versioned today. Compatibility currently depends on serde defaults and ad hoc field additions.

Why this matters

The project already ships save/load and replay as core features. Future schema changes will be much safer if saves declare a format version and the loader has explicit compatibility behavior.

Current examples

  • SaveFile includes fields like advanced_stats, game, and snapshots, but no format_version.
  • Older saves are partly tolerated through #[serde(default)], but there is no formal migration contract.

Acceptance criteria

  • Save files include an explicit format version.
  • The loader documents how it handles supported older versions and unsupported future versions.
  • If migration is needed, implement a minimal migration path or a clear error for unsupported versions.
  • Add tests covering at least one older-format fixture or synthetic JSON payload.
  • README or maintainer docs briefly note the compatibility strategy.

Notes

This issue is about making save compatibility intentional, not about guaranteeing indefinite backward compatibility forever.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions