Software Engineering Metrics

テスト: 検証スイート

実行する

just test
# or
python3 tests/validate.py

どこからでも実行でき、必要なのはPython 3だけです(サードパーティのパッケージもネットワークも不要)。検査ごとに1行を出力し、 どれかの検査が失敗すると非ゼロで終了するので、CIでも、プリコミットフックとしても使えます。

検査する内容

  • 期待されるトピック数(スクリプト冒頭の定数)。
  • 各部の中で、N.0から始まる連続した番号。
  • すべてのトピックで、H1がファイル名の小数と一致する。
  • H1タイトルがspec/structure.mdと、先頭の小数だけでなく1文字ずつ一致する。
  • すべての内容トピック(第1部から第8部、トピックN.1以降)に必須セクションがあること。テンプレートとまったく同じ順序で。
  • すべての内容トピックの最小語数(1,500語)。意図的な例外のためにスクリプト内に許可リストがあります。
  • どのMarkdownファイルにもエムダッシュがない。
  • エンダッシュは数字の間だけ。「2.1–2.8」は通り、それ以外はすべて失敗します。
  • 禁止フレーズがない(「not only」、「but also」、「load-bearing」)。
  • 内部の.mdリンクがすべて解決する。
  • 本文中の相互参照が実在のトピックを指す: ディスク上に対応するファイルのないトピック番号への参照は、公開サイトのトピックリンク自動化と 同じ参照パターンを使って失敗します。
  • Wikipediaリンクの形式が正しい(https://en.wikipedia.org/wiki/...)。
  • spec/structure.mdがディスク上のファイルと一致する。両方向で。
  • README、ホームページ、コンテンツページがすべてのトピックにリンクする。

検査が失敗したとき

失敗した行は、ファイルと問題を示します。よくある対処:

  • エムダッシュが見つかった: 「—」を取り除くように文を書き直します。ただ削除しないでください。
  • セクションの欠落: トピックテンプレートから、足りない##セクションを追加します。
  • 構造の不一致: spec/structure.mdを更新せずにトピックを追加または名称変更した、あるいはその逆。両者を揃え直します。
  • 壊れたリンク: パスを直すか、名称変更後に更新します。
  • 番号の抜け: 部がN.0から連続するように番号を振り直します。

検証スイートを超えて

  • just spellはリポジトリに対してcodespellを実行します。設定は、誤検出の無視リストを含め、 pyproject.tomlの[tool.codespell]セクションです。
  • just statsはtools/stats.pyからMarkdownのレポート(トピックごとの語数、薄いトピック、Wikipediaリンク、参考文献エントリ)を出力します。

継続的インテグレーション

  • .github/workflows/test.ymlは、すべてのプルリクエストと、mainではないブランチへのプッシュで実行されます。検証スイートとcodespellです。 このリポジトリはサイトをビルドもデプロイもせず、レンダリングは別のsoftware-engineering-metrics.github.ioリポジトリで行われます。
  • .github/workflows/links.ymlは、lycheeで外部リンクを毎週検査し(無視パターンは.lycheeignore)、 結果を1つの「Link checker report」イシューに保ちます。外部リンクは意図的にPRの経路から外してあります。

テストの対象外

スイートは構造とスタイルを検査し、真実は検査しません。参考文献が実在するか、本文が正確かは判断できません。引用と事実は、手作業か調査のパスで検証してください。 Wikipediaリンクの存在(形式とは別)もネットワーク検査が必要で、スイートがオフラインで動けるよう、意図的に省いています。