[takemi-ohama]

snapshot で既にある世代へ --full を指定したとき、その世代を full で作り直せるようにしました。作り直しでは、元の世代をいったん仮の名前で控え、新しい世代ができてから入れ替えます。この PR は #458 として、スプリント m8b のブランチへ集めます。

利用者向けの変化

• snapshot で既にある世代へ --full を指定すると、その世代を full で作り直す
• 作り直しの間、元の世代は仮の名前で控えておき、新しい世代ができてから入れ替える

移行の手順

• 無し

変更の要点

• lib/devbase/snapshot/manager.py: 既にある世代へ full を作る場合の処理を足しました。元の世代を仮の名前へ控え、作成後に入れ替えます。
• 確定仕様 docs/specifications/snapshot-series.md に世代の作り直しを書きました。backup_command の引数と構成要素にも足しています。docs/specifications/snapshot-exclude.md も合わせて直しました。
• 利用者向けの文書 docs/user/cli-reference/05-snapshot.md と docs/user/snapshot-guide.md に、既存の世代への --full の作り直しを書きました。CHANGELOG にも書いています。
• 課題: 既存の世代の名前で snapshot create --full を打つと、full.tar.zst が変更分だけになり復元でファイルを失う #458

テスト

• tests/snapshot/test_rebuild_generation.py を足しました。世代の作り直しについて、成功・失敗・印を縛ります。
• tests/snapshot/test_backup_real_tar.py では、実の tar の中身を縛ります。
• tests/snapshot/fake_tar.py と既存の snapshot のテストを、変更に合わせて直しました。

ステップ	exit	結果
test-limited	0	範囲テスト 1 本（166.0 秒 / 戦略 local-full）が ok
design-tests	0	設計文書 1 件（issues/issue-458-design.md）に名前の出るテスト 4 件が、すべて HEAD にある
design-specs	0	変えたパス 15・シンボル 55 を含む既存の確定仕様と変更履歴 19 件を確認

設計と違う点

設計の箇所	違い	理由
決定 3（今のテストがそのまま通る）	期待（控えのコマンドの文字列・meta.yml・snapshot.yml）は変えていないが、既存の 6 つのテスト（test_archive_layout.py ほか）の docker の差し替えを、決め打ちの full.tar.zst・snapshot.snar ではなくコマンドに書かれた名前へ書く共通の tests/snapshot/fake_tar.py に替えた	差し替えが決め打ちの名前で書くと、作り直しの経路で snapshot.snar.new ができず入れ替えが失敗する。期待の側は 1 文字も変えていない

設計の決定と違えたところ

• 設計の構成要素にない小さなメソッドを 3 つ足した: _full_meta（新しい世代と作り直しで同じ meta.yml の中身を組む）・_has_previous_files（作り直すかの判定。決定 3）・_replace_snap_meta（meta.yml.new へ書いて os.replace する。設計では _install_rebuilt_full の中で行うとしていた処理を切り出した）。振る舞いは設計のとおり
• 定数は設計の 3 つ（FULL_ARCHIVE_TMP・SNAR_FILE_TMP・META_FILE_TMP）に、SNAP_META_FILE（meta.yml）と REBUILDING_KEY（rebuilding）を足した
• docker を差し替えたテストの 6 か所が、書くファイルの名前を固定（full.tar.zst・snapshot.snar）で置いていた。作り直しは仮の名前へ書くため、コマンドの -o と --listed-incremental= から名前を拾う共通の関数 tests/snapshot/fake_tar.py に揃えた
• 用語集の「世代の作り直し」は設計の時点で入っていたため、docs/glossary/glossary.json・docs/glossary.md は変えていない

手で確かめたこと

• 実の GNU tar（1.35）と zstd で走るテスト（tests/snapshot/test_backup_real_tar.py に足した 3 件。受け入れ条件 1・2・7）は macOS の手元では飛ぶため、python:3.12-slim に zstd を入れたコンテナで走らせ、通ることを確かめた。同じテストを変更前の manager.py で走らせると 3 件とも落ちることも確かめた
• env -u DEVBASE_ROOT uv run --locked pytest tests/ -q: 4251 passed, 27 skipped
• uvx ruff check --select=E9,F63,F7,F82 lib: 通った
• 固有の語の検査: 語の一覧が無いため飛ばした（検査していない）
• CHANGELOG の検査（changelog_check.py）は pull_request のイベントでしか走らないため、手元では走らせていない

残した事項

• 実の devbase-snapshot のコンテナで、作業用の名前の世代へ --full を 2 回打って作業用のボリュームへ復元する確認は、リリース後テストで行う（要求の検証手段）
• Linux の実機で、コンテナが root で書いた仮の名前のファイルをホストの利用者が改名・削除できることは、リリース後テストで見る（設計の「未確認のまま残ること」）
• 要求の未決 1（すでに傷んだ世代を見つける処理）は設計の決定 5 の案のとおり処理を足さず、CHANGELOG.md で条件と取り直しを案内した。承認ゲートで利用者が決める

モード: standard / 通した工程: 実装 → 完了判定 → Pull Request

🤖 Generated with Claude Code