Repository navigation
ドキュメントを読者別に再編し、v0.6.0 の現状に合わせる - #42
Merged
Merged
Conversation
SPEC.md は章ごと（§7 と §12 は節ごと）に docs/spec/ へ、DECISIONS.md は 判断ごとに docs/decisions/D-NNN.md へ分ける。分けたファイルを順に連結すると 元のファイルと一致する（目次として足した行を除く）。利用者向けは docs/user-guide/、運用者向けは docs/admin-guide/、TASKS.md は作業記録として docs/development/ へ移す。
コード・テストのコメント中の docs/SPEC.md などを新しいパスへ直す。 SPEC §n と D-n の表記はそのまま残す。tests/config.rs は §13 の toml ブロックを docs/spec/13-config.md から読む。docs 内の参照は相対リンクにする。
docs/README.md に読者別の地図・参照の読み方・旧パスとの対応を置く。 spec/ と decisions/ の各ファイルは先頭見出しを H1 にそろえ、本文中の D-n と SPEC §n を相対リンクにする（コードブロックと見出しの中は除く）。 tasks-history.md は履歴である旨を冒頭に書き、今後の設計書・計画の置き方を docs/development/README.md に書く。
git 管理外の docs/superpowers/ にあった端末への配信（P5）、CD 画面、 記録画面、Inbox の再判定、スマホ版の設計書と計画を照合し、仕様に 無かった挙動・境界値・API の細部を docs/spec/ へ、判断の理由を既存の D-58 / D-98 / D-106 / D-115 へ追記する。食い違いは実装に合わせる。 コードのコメントで設計書や「仕様 ③」などの節番号を指していた箇所は SPEC §7.11 などの仕様の節へ付け替える。§17 で移行手順の §2 を仕様の §2 へ誤ってリンクしていたのも直す。
user-guide: CD の吸い出し（実装済み）、記録画面、Inbox の承認の列と 再判定、Derived のバッジ（O / A）、端末（§15）などを今の画面に合わせて 直す。DSL のフィールドと演算子を実装（dsl.pest）と突き合わせて直す。 admin-guide: README の起動節と運用手順のカスタムアプリの作り方を install.md にまとめる。作者の環境の IP・プロキシ構成・曲数などを例示に 置き換え、移行手順のリリース時の再移行（実施済み）を汎用の任意手順に 書き直す。仕様のステータス表記を v0.6.0 に合わせる。
README は外から見た人向けに、できること・設計の考え方・現状（v0.6.0）・ 動かし方・ドキュメントの案内にする。CONTRIBUTING に開発環境と変更の 進め方を、CHANGELOG に v0.1.0〜v0.6.0 の要点を書く。LICENSE は Cargo.toml の MIT に合わせる。AGENTS.md は新しい配置と、設計書を docs/development/ に作業中だけ置いて仕様へ移す進め方に直す。
README と AGENTS.md の「非可逆から非可逆へ変換しない」に Apple 向けの aac 系統の例外（D-75）を書く。README の「単一コンテナ」と「すべて 巻き戻せる」を実態に合わせて限定する。ロックモードでは画面も 503 に なるので、/health と起動ログを見る案内にする。短い検索語の LIKE を 正確に書く。仕様の README は、実装が正しいと確かめたときだけ仕様を 直すと書く。SD のボリューム UUID と検証用の Mac のホスト名を例示に 置き換える。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ドキュメントを v0.6.0 の現状に合わせ、一般的な OSS の分類（リポジトリ直下の定番ファイル + docs/ を読者別）に整理する。
構成
docs/user-guide/（旧 USERGUIDE.md、DSL.md）docs/admin-guide/（install.md を新設、旧 OPERATIONS.md、MIGRATION.md）docs/spec/（旧 SPEC.md を章ごと、§7・§12 は節ごと）、docs/decisions/（旧 DECISIONS.md を 1 判断 1 ファイルD-NNN.md）docs/development/（旧 TASKS.md を履歴として、今後の設計書・計画は作業中だけここに置く）直下に CONTRIBUTING.md、CHANGELOG.md（v0.1.0〜v0.6.0）、LICENSE（MIT、Cargo.toml に合わせる）を足し、README は外から見た人向けに書き直した。地図と旧パスとの対応表は
docs/README.md。辿れるようにしたこと
D-62/SPEC §7.3の表記は変えていない。番号はファイル名と目次でそのまま引けるD-nとSPEC §nは相対リンクにした内容の更新
docs/superpowers/の設計書・計画（約 30 本）を実装と照合し、仕様に無かった挙動・境界値・API を spec へ、判断の理由を既存の D-n へ追記した。食い違いは実装に合わせた。コードのコメントで設計書や「仕様 ③」を指していた箇所は仕様の節へ付け替えた（db/migrations/0002_devices.sqlは書き換えないので旧パスのまま。対応表で引ける）コードの変更はコメントと
tests/config.rs（§13 の toml ブロックをdocs/spec/13-config.mdから読む）だけ。codex のレビュー済み。