Skip to content

docs: fix unsafe WAL recovery advice and align docs with milestones - #408

Merged
adityamukho merged 2 commits into
mainfrom
claude/magical-wright-lbxulz
Sep 26, 2026
Merged

adityamukho merged 2 commits into
mainfrom
claude/magical-wright-lbxulz

Conversation

@adityamukho

Copy link
Copy Markdown
Collaborator

Summary

This PR fixes doc problems found in a full docs and wiki review (see #383).

  • Unsafe recovery advice (most important). docs/ERROR_REFERENCE.md WAL-001, WAL-002 and STG-011 told users one of two things:
    • they could delete the .wal file with no data loss ("committed facts are in the .graph file"), or
    • they could rebuild a database from the WAL alone.
      Both are wrong. Transactions committed since the last checkpoint exist only in the WAL, and the WAL holds nothing older than that checkpoint. The new text says to copy both files first, to checkpoint with the version that wrote the WAL, and what is lost if the WAL is deleted.
  • Broken links. About 50 links in ERROR_REFERENCE.md pointed at ../../.wiki/..., a local clone path. They now use full wiki URLs, with anchors mapped to the real headings. One ../BENCHMARKS.md link was also wrong.
  • ROADMAP and CLAUDE.md now match the live milestones:
    • v2.0.2 is the final planned v2.x release.
    • v3.0.0 is format v8 and data integrity.
    • v3.1.0 holds the features.
      CLAUDE.md now documents error.rs, magic_sets.rs, fault_inject.rs and src/browser/.
  • README:
  • SECURITY.md: 2.x is the supported line.

The PHILOSOPHY.md stability wording is left for #397, because it needs a policy decision. Wiki fixes are pushed separately to the wiki repo.

Type of change

  • Documentation / tests only

Checklist

  • cargo test passes (--lib error_reference and --lib registry, which parse ERROR_REFERENCE.md, were rerun; the full suite passed at 69da4b2 with 1,168 passed and 8 ignored)
  • CHANGELOG.md updated under Unreleased
  • I have read PHILOSOPHY.md and this change aligns with it

Notes for reviewer

Please check the new WAL-002 steps ("open with the version that wrote the WAL and call checkpoint()") against how you want downgrades handled.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BBxgR4mnF8VMVGa42idcxx


Generated by Claude Code

- ERROR_REFERENCE: WAL-001/WAL-002/STG-011 said deleting the .wal loses
  no data, or that a database can be rebuilt from the WAL alone. Both
  are wrong. Replace with safe steps. Fix ~50 wiki links that pointed
  at a local .wiki path.
- ROADMAP/CLAUDE.md: match the v2.0.2, v3.0.0 and v3.1.0 milestones.
  Document error.rs, magic_sets.rs, fault_inject.rs and src/browser/.
- README: state MSRV 1.89, show the #371 known issue, fix Maven
  coordinates (io.github.project-minigraf), Android on Maven Central,
  and point binding downloads to the binding repos.
- SECURITY.md: 2.x is the supported line.

Refs #383, #397, #399

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BBxgR4mnF8VMVGa42idcxx
@codecov

codecov Bot commented Sep 26, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@adityamukho
adityamukho merged commit dee008f into main Sep 26, 2026
17 checks passed
@adityamukho
adityamukho deleted the claude/magical-wright-lbxulz branch September 26, 2026 09:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants