正本を一つにできない並行記載は、対応表+リリース前フックの機械ドリフト検知で守る
設計判断
運用
ドキュメント
判断
運用
同じ契約・ルール・設定値を複数のドキュメントや配布物に並行記載せざるを得ないことがある。配布物が自己完結を要求される、パッケージ・プラグイン境界をまたぐファイル参照が成立しない、片方が単独利用されるため他方への依存を持てない、といった構造的理由がある場合、「正本+参照」への一本化は選べない。人力の「変更時は両方揃える」ルールは実際にずれる(実測: 並行記載の用語ずれが発生してから発覚)。
判断基準
まず一本化(正本1箇所+他は参照かミラー)を検討し、次のいずれかに当たる場合だけ重複を受け入れて機械検知に切り替える。
- 参照先が別の配布物・別リポジトリで、利用環境によって参照が壊れる
- 文書が単独で読まれる・単独で機能する必要があり、参照化すると不完全になる
- 並行箇所に「同文であるべき部分」と「正当な差異」が混在し、丸ごとの複製・ミラーが成立しない
実装
対応表(どのファイルのどの条項同士が同文であるべきか)をチェックスクリプト内の定数として持ち、リリース前フック(バージョン更新前フック等)で照合して、不一致は該当箇所を列挙して非0終了にする。登録するのは意図的に同文とする範囲のみで、正当な差異は照合範囲から外す(一致アンカーを差異の手前で打ち切る等)。
落とし穴(検知器自体の false green)
- 各ファイルで最初の一致だけを取り出して比較すると、同じ文言が別の節・例示にも現れたとき別行同士を比較して green になる。全マッチを収集し、マッチ件数の差も不一致として扱い、同順位同士を比較する。
- 比較前の正規化で空白を全削除すると、空白の有無という文法差まで同一視する。正規化は空白の単一スペース圧縮までに留める。
いずれも実際のクロスレビューで再現付きで指摘された型で、検知器は素朴に書くと「常に green の飾り」になりやすい。
検証
導入時に故意ずれ検体(登録条項の1語変更・片側への重複行挿入・空白除去)でそれぞれ非0終了と該当箇所列挙を確認する。検知器の検知力自体をテストしない導入は意味をなさない。副次効果として、初回実行が既存の実在ドリフトを掘り当てることが多い(実測: 導入時に2件検出、うち1件は実行時エラーになるモデル名の取り違え)。