82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
|
# Docs Layout (SSOT)
|
|||
|
|
|
|||
|
|
Status: SSOT
|
|||
|
|
Scope: `docs/development/current/` 以下の「置き場所ルール」と、SSOT/履歴メモの混在を防ぐための最小ガイド。
|
|||
|
|
|
|||
|
|
## 目的
|
|||
|
|
|
|||
|
|
- 入口（読む順序）と、詳細（設計図/調査/Phaseログ）を分離して迷子を防ぐ。
|
|||
|
|
- “Phase 文書が増えても” SSOT が埋もれないようにする。
|
|||
|
|
- 大規模移動はしない（リンク切れ回避）。以後の追加分から秩序を作る。
|
|||
|
|
|
|||
|
|
## ディレクトリの役割（推奨）
|
|||
|
|
|
|||
|
|
### `docs/development/current/main/`（入口・現状）
|
|||
|
|
|
|||
|
|
ここは「まず読む」入口を置く場所。SSOT を全部ここに置かない。
|
|||
|
|
|
|||
|
|
- 入口（例）: `00-Overview.md`, `01-JoinIR-Selfhost-INDEX.md`, `10-Now.md`, `20-Decisions.md`, `30-Backlog.md`
|
|||
|
|
|
|||
|
|
### `docs/development/current/main/design/`（設計図・SSOT寄り）
|
|||
|
|
|
|||
|
|
設計の SSOT / 長期参照の設計図を置く。
|
|||
|
|
|
|||
|
|
- 原則: Phase 依存のログ/作業記録は置かない（それは phases へ）。
|
|||
|
|
- 例: JoinIR の設計、Boundary/ExitLine の契約、Loop パターン空間、runtime/box 解決の地図。
|
|||
|
|
|
|||
|
|
### `docs/development/current/main/investigations/`（調査ログ）
|
|||
|
|
|
|||
|
|
不具合調査のログ、切り分け、暫定メモを置く。
|
|||
|
|
|
|||
|
|
- 原則: “結論” は `10-Now.md` / `20-Decisions.md` / 該当 design doc に反映し、調査ログ自体は参照用に残す。
|
|||
|
|
- 原則: 調査ログを SSOT にしない（参照元を明記して“歴史化”できる形にする）。
|
|||
|
|
|
|||
|
|
### `docs/development/current/main/phases/`（Phaseログ）
|
|||
|
|
|
|||
|
|
Phase ごとの記録・完了サマリ・実装チェックリストを置く。
|
|||
|
|
|
|||
|
|
- 推奨構造:
|
|||
|
|
- `docs/development/current/main/phases/phase-131/`
|
|||
|
|
- `docs/development/current/main/phases/phase-131/131-03-llvm-lowering-inventory.md`
|
|||
|
|
- `docs/development/current/main/phases/phase-131/131-11-case-c-summary.md`
|
|||
|
|
|
|||
|
|
## ドキュメントの種別（ファイル先頭に明記）
|
|||
|
|
|
|||
|
|
追加/更新する文書の先頭に、最低限これを付ける。
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Status: SSOT | Active | Historical
|
|||
|
|
Scope: ...
|
|||
|
|
Related:
|
|||
|
|
- <入口/SSOT>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- `SSOT`: 現行の正本（同じテーマの“別名ファイル”を増やさない）。
|
|||
|
|
- `Active`: 現行だが SSOT ではない（実装の手順書/チェックリスト等）。
|
|||
|
|
- `Historical`: 参照用（当時の調査・ログ）。入口や Now から “歴史” としてリンクする。
|
|||
|
|
|
|||
|
|
## 移行ポリシー（リンク切れ防止）
|
|||
|
|
|
|||
|
|
既存のファイルは大量移動しない。移動が必要な場合は必ず旧パスに“転送スタブ”を残す。
|
|||
|
|
|
|||
|
|
例（旧ファイルの内容を最小化）:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
# Moved
|
|||
|
|
|
|||
|
|
Moved to: docs/development/current/main/phases/phase-131/131-03-llvm-lowering-inventory.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 命名（推奨）
|
|||
|
|
|
|||
|
|
- Phase 文書: `phase-<N>/` + `<N>-<NN>-<topic>.md`（同一フェーズ内で並べ替えが自然）
|
|||
|
|
- 調査ログ: `<topic>-investigation-YYYY-MM-DD.md` など（時系列が分かる形）
|
|||
|
|
- 入口/SSOT: “Phase番号を入れない” ことを基本にする（寿命が長いので）
|
|||
|
|
|
|||
|
|
## 運用の最小ルール
|
|||
|
|
|
|||
|
|
- 新しい Phase 文書は `main/phases/` に入れる（`main/` 直下に増やさない）。
|
|||
|
|
- 設計図（SSOT）は `main/design/` に寄せる（Phase の完了サマリと混ぜない）。
|
|||
|
|
- `10-Now.md` は「現状の要約＋正本リンク」に徹し、詳細ログの本文は抱え込まない。
|
|||
|
|
|