Plan for introducing file format version 3 (v3 support, CLI version 0.0.10 and 1.0.0 roadmap)

[yoshi389111]

We need to introduce support for a new file format version (v2 /v3 ) while maintaining backward compatibility with the existing v1 format. (changed 2025-07-08)

This issue is to plan and track the overall approach for:

• Adding support for writing/reading format v2 /v3 (changed 2025-07-08)
• Managing the default output format across CLI versions
• Communicating changes to users

---

Goals

1️⃣ Add support for reading format v2 /v3 (alongside v1) (changed 2025-07-08)

• Decryption should automatically detect the format version from the file header
• Error out cleanly if an unknown format version is encountered

2️⃣ Add support for writing format v2 /v3 (changed 2025-07-08)

• Introduce a CLI option (e.g. -F 2) to specify the format version to use during encryption
• Default output should remain v1 initially

3️⃣ Plan two CLI releases:

• v0.0.9
  • Default: output format v1
  • Supports: writing format v2 with -F 2
  • Reads: format v1 and v2 automatically
  • Release notes should encourage testing format v2
• v0.0.10 (added 2025-07-08)
  • Default: output format v1
  • Supports: writing format v3 with -F 3
  • Reads: format v1, v2 and v3 automatically
  • Release notes should encourage testing format v3
• v1.0.0
  • Default: output format v2 v3 (changed 2025-07-08)
  • Supports: writing format v1 /v2 with -F (changed 2025-07-08)
  • Reads: format v1, v2 and v3 automatically (changed 2025-07-08)
  • Clearly announce the change of default in release notes

4️⃣ Ensure good error handling and clear user feedback

• Helpful error message for unsupported versions
• Update --help text with -F option usage

---

Proposed Tasks / Sub-Issues

• Implement reading support for format v2
• Implement writing support for format v2
• Add -F option to specify format version during encryption
• Update CLI help text
• Write release notes for v0.0.9
• Add tests for format v2 reading/writing
• Add tests for format v3 reading/writing (added 2025-07-08)
• Implement reading support for format v3 (added 2025-07-08)
• Implement writing support for format v3 (added 2025-07-08)
• Write release notes for v0.0.10 (added 2025-07-08)
• Prepare plan/notes for v1.0.0 release
• Document future default switch to format v2 v3 (for v1.0.0) (changed 2025-07-08)

---

Notes for Users

We plan to maintain backward compatibility:

• Older versions will reject unknown format versions, as before
• v0.0.9 will allow users to try format v2 by explicitly selecting it
• v0.0.10 will allow users to try format v3 by explicitly selecting it (added 2025-07-08)
• v1.0.0 will switch the default to format v3 but still support format v1 /v2 (changed 2025-07-08)

---

This issue will serve as the master tracking issue. Individual sub-issues can be created for each of the tasks above as needed.