このプロジェクトについて
この本のプロジェクト・ドキュメントです。どう組み立てられているか、どうビルドして検証するか、そして信頼できる情報源がどこにあるか。 本そのものについては目次を参照してください。
プロジェクトの地図
- 本:
locales/の下に4つのロケールで公開されています。 spec/locales.mdを参照してください。 このロケール、en-gb-oxendict/topics/(63ファイル)、en-gb-oxendict/front-matter/、第9部の付録が手書きの原典であり、en-001、en-gb、en-usはそこから派生します。 - 信頼できる情報源: リポジトリ直下の
spec/(サイトには公開されません)。構造はspec/structure.md、 書き方のルールはspec/conventions.md、綴りはspec/oxford-spelling.mdに宣言されています。ほかはすべてこれに合わせて作られます。 - ツール:
tools/localize.pyが他の3つのロケールを派生させ、tools/gen_nav.pyがナビゲーションを生成し、tests/validate.pyが仕様を強制し、justfileがそれらをつなぎます。 - コントリビューター向けガイダンス: リポジトリ直下の
AGENTS.mdと、 貢献セクションのガイド。
ビルドと検証
検証スイートはPython 3だけで、ほかの依存関係もネットワークアクセスも不要で動きます。タスクはjustで実行します。
just test # validate structure, style, links, and spec-vs-disk
just nav # regenerate the generated navigation files
just check # nav, then test
just stats # topic and word countsこのリポジトリは本の内容と仕様を保持します。別の software-engineering-metrics.github.io リポジトリがウェブサイトにレンダリングします。
ここでの仕様駆動開発の仕組み
仕様が先に来ます。spec/structure.mdは、どのトピックが存在し、どう番号付けされるかを定めます。spec/conventions.mdは、
それらをどう書くべきかを定めます。トピックはその両方を満たすように執筆されます。tools/gen_nav.pyはトピックからナビゲーションを派生させ、 tests/validate.pyは結果を仕様と突き合わせて検証します。トピックと仕様が食い違えばテストは失敗し、それが両者を揃え直す合図です。
これがずれを防ぎます。仕様、トピック、生成されたナビゲーション、テストのすべてが一致して初めて、変更は「完了」です。
知っておく価値のある設計判断
- フラットで小数番号のトピック。 ファイルは
locales/<locale>/topics/PP-CC-slug.mdで、どのロケールでも同じslugです。 部は整数、トピックは小数、N.0は部の導入です。これにより安定した識別子が保たれ、ツールはディレクトリ木なしで並べ替えとグループ化ができます。 - 手書きのロケール1つ、派生が3つ。
en-gb-oxendictはオックスフォード綴りで、国際標準化団体の多くのハウススタイルです (spec/oxford-spelling.md参照)。en-001、en-gb、en-usはそこから機械的に派生するため、翻訳が原典からずれることはありません。 - 生成されるナビゲーション。 目次、コンテンツページ、主題索引は生成されるので、トピックからずれることはありません。
- オフラインで依存関係のないテスト。 スイートは標準ライブラリだけを使うので、CIやプリコミットフックを含め、どこでも動きます。
- 相互参照はプレーンテキストのまま。 本文は、仕様が求めるとおり、トピックを小数番号で参照します(「トピック2.1を参照」)。 それらの参照をリンクに変えるのはレンダリングするサイトの責任です。
- エムダッシュは使わない、ルールでもテストでも。 意図的な文体の選択で、本が育っても守られるよう強制されています。
- すべての指標ファミリーが自身の操作の経路を名指しする。 これは、姉妹プロジェクトの
software-engineering-guideには 対応するものがない、テンプレート唯一のルールです。この本の主題全体が測定であるため、測定そのもののリスクは暗黙ではなく、 最優先の扱いでなければならないからです。