言語判定のリポジトリに、拡張子や新しい言語を足す

## 言語判定の各部分を、どのファイルとツールが受け持つかを調べる 編集前に、言語判定の各要素をどのファイルとツールが管理しているか特定する。 - 言語名、拡張子、ファイル名、言語の属性を管理する言語レジストリ。 - 曖昧なファイルに対するヒューリスティック規則とその実装。 - 統計的分類器と、実際のコードからなるサンプルコーパス。 - 構文強調表示に使う文法レジストリ。 - 取り込み済みの文法ソースと、キャッシュされたライセンスデータ。 - 保守スクリプト、テスト、継続的インテグレーションの入口。 これらを連動する契約として扱う。メタデータの変更には、単独の編集だけでなく、サンプル、ヒューリスティック、生成識別子、文法データ、テスト、証拠が必要になる場合がある。 ## リポジトリの開発コンテナで準備し、用意されたスクリプトを使う 利用できる場合は、リポジトリが保守する開発コンテナまたはホスト型環境を優先する。その環境には、指定された言語ランタイム、パッケージツール、コンテナランタイム、ネイティブライブラリ、プロジェクトの全依存関係が含まれている必要がある。 ローカルで作業する場合は、次を行う。 1. 標準の初期設定コマンドを実行する。 2. リポジトリの依存関係ランナーを通じて、ライブラリまたはコマンドラインツールを呼び出す。 3. 文書化された保守スクリプトを使い、その処理を手作業で再現しない。 4. エンコーディング判定、リポジトリアクセス、文法関連の作業に必要なネイティブ依存関係が存在することを確認する。 手元の場当たり的な実行が成功しただけで、サポート対象の環境でも合格すると判断しない。 ## 既存の言語に拡張子をアルファベット順で足し、実際のサンプルを添える 既存の言語へファイル拡張子を追加する場合は、次を行う。 1. 正本の言語項目を更新する。 2. 拡張子一覧を、指定された大文字・小文字を区別するアルファベット順に保つ。大文字を小文字より先に置き、主要拡張子を先頭にする。 3. 担当言語の下に、現実の利用状況を代表するサンプルファイルを追加する。 4. 別の言語と拡張子を共有する場合は、少なくとも二つのサンプルを用意し、曖昧性を解消するヒューリスティックを追加する。 5. メタデータとヒューリスティックの動作に対するテストを追加または更新する。 単純な挨拶プログラムなど、チュートリアルで定番の例を分類器の証拠に使わない。サンプルは、判定器が認識すべき実際のコードを反映する必要がある。 ## 新しい言語を、文法の登録とスクリプトで作るIDつきで足す 新しい言語には、レジストリのラベルだけでは足りない。 1. 言語項目を追加するが、生成される識別子は未設定のままにする。 2. 標準の文法ツールを通じて、承認済みで互換性のある構文強調表示用の文法を登録する。 3. 検証可能な原典から、実際の利用状況を代表するサンプルファイルを追加する。 4. 識別子を手動で割り当てず、識別子生成スクリプトを実行する。 5. いずれかの拡張子を共有する場合は、少なくとも二つのサンプルと、テスト済みの曖昧性判定規則を追加する。 6. メタデータ、文法登録、分類、生成された変更をまとめて確認する。 レジストリのヘッダーにある指針、フィールド要件、大文字・小文字を区別する並び順を維持する。 ## 拡張子がかぶる言語を見分ける正規表現のルールを、テスト付きで書く ヒューリスティックは、広範な誤検出を生まずに、実際の曖昧さを解消する必要がある。 - 競合する言語を区別できる、最小限の特徴的な証拠に一致させる。 - すべてのパターンを入力サイズに対して線形に保つ。 - 正規表現によるサービス拒否攻撃を受けやすい構造を避ける。 - リポジトリで必須の正規表現エンジンが対応する構文だけを使う。 - 正例、競合言語の例、判定境界に近い例をテストする。 - ヒューリスティックまたはサンプルの変更で判定動作が変わり得る場合は、分類器の交差検証を実行する。 すべてのヒューリスティックにテストが必要である。対象を認識できても無関係なファイルまで拾う規則は受け入れない。 ## 生成されたファイルは手で直さず、保守コマンドで作り直す 生成されたレジストリ、モジュール宣言、取り込み済み文法の内容、キャッシュされた文法ライセンスファイルを手作業で編集しない。文法の追加または置き換えには、担当する保守コマンドを使い、そのコマンドが生成した変更をすべて確認する。 文法を受け入れる前に、次を確認する。 - プロジェクトが使う構文強調表示形式との互換性。 - ライセンスが承認済みの一覧に含まれていること。 - 標準の原典URLとライセンス記録が保たれていること。 - サポート対象のコンテナ環境で文法固有の検証が通ること。 生成結果が誤っている場合は、生成結果へつぎはぎせず、元の入力または生成ワークフローを修正する。 ## 分類器の交差検証と、テスト一式を通す 最も範囲の狭い関連チェックから始め、その後にリポジトリで必須の検証をすべて実行する。 1. 変更したメタデータと並び順を検証する。 2. 新しいサンプルとヒューリスティックのテストを実行する。 3. 判定境界が動く可能性がある場合は、分類器の交差検証を実行する。 4. 標準の依存関係ランナーを通じて、テスト一式を実行する。 5. 継続的インテグレーションで同じ必須段階が合格することを確認する。 失敗を確認し、誤検出、生成ファイルのずれ、ネイティブ依存関係の欠損、無効な文法データ、無関係な言語への意図しない変更がないか調べる。 ## 変更提案を出す前に、利用数の証拠とサンプルのライセンスを示す 変更提案を提出する前に、次を行う。 - 用意された依頼テンプレートを使い、無関係な節だけを対象から外す。 - 追加する拡張子ごとに、forkを除外した公開検索の証拠へリンクする。 - 一般的な拡張子では索引済みファイルを少なくとも2000件、リポジトリごとに通常一度だけ現れる名前では200件示す。 - 特定の利用者が異常に大きな割合を占める場合を考慮し、異なる利用者とリポジトリの組み合わせへ妥当に分布しているか確認する。 - 各サンプルを、変更提案用のforkではなく元の原典へリンクする。 - 各サンプルコードのライセンスを個別に明記する。 - 必須の全テストと継続的インテグレーションのチェックに合格する。 - 変更の焦点を保ち、無関係なリファクタリングを組み合わせない。 いずれかの要件を満たしていない場合は、変更提案を提出しない。どの証拠、ライセンス、テスト、範囲条件が不足しているかと、先に完了すべき内容を説明する。