技術ツールやリンクの一覧に届いた、新しい投稿を確かめる

## 一覧のファイルを1つだけの大もとにし、サイトとデータはそこから作る 人が読める1つの目録文書を正本として扱う。 派生成果物を個別に編集せず、その正本から索引、構造化データセット、静的ページを生成する。 実装言語の見出しではなく、主題カテゴリーの下に項目を整理する。 1つのリソースが主題カテゴリーを変えずに複数言語へ対応できるよう、各項目のインラインタグに対応言語を記録する。 データの流れを文書化する。 1. 目録文書に選定済み項目を保存する。 2. parserが項目を検証し、承認された外部メタデータを補足して、構造化データセットを書き出す。 3. site generatorはデータセットがあれば読み込み、なければローカルpreview用に目録を直接解析する。 4. continuous integrationがparserとgeneratorを実行し、生成されたsiteディレクトリだけを公開する。 parser、generator、deploymentの挙動をこの取り決めと一致させる。 生成ページやデータセットを、競合する別の正本にしない。 ## 一覧の項目を、言語タグつきの1つの書き方にそろえる parserが認識できる項目形式を1つ定義し、句読記号も取り決めの一部として扱う。 標準的な項目は、リンク付き名称、1つ以上のインライン言語タグ、説明で構成する。``- [Name](https://example.org) - `Language` - Description.`` 次の規則を適用する。 - 新しい非商用項目には、必須の区切り文字が続く言語タグを1つ以上含める。 - 説明は、任意のソースリポジトリリンクより前でピリオドを付けて終える。 - 新しいリンクには`https://`を使う。 - 商用または専有リソースは専用カテゴリーに置く。 - 言語タグを省略できるのは、商用カテゴリーまたは明示的に言語と無関係なカテゴリーだけとする。 - 投稿者向けの貢献ガイドを、投稿規則の正本として維持する。 周辺構造を変えずに、複数の言語タグを受け入れる。 完結した説明の後には、任意のリポジトリリンクを許可する。 同じ項目文法に従う場合は、エコシステム固有のパッケージリンクも有効として扱う。 1件の不正な投稿に合わせてparserのpatternを緩めない。 ## 新しい項目は厳しく確かめ、前からある項目は注意として伝えるだけにする 検証、解析、公開には、リポジトリで文書化された環境とtask wrapperを使う。 必要なruntime versionを守り、正規のdependency commandで依存関係をインストールする。 2つの検証モードを使う。 1. 変更検証では、選択した基準revisionに対して追加された項目だけを確認する。 2. 目録全体の検証では、すべての項目を確認する。 新規項目では、重複、不正なリンク、URL方針違反の指摘をerrorとして扱う。 目録全体では、strict flagが明示的に選ばれていない限り、同種の既存問題をwarningとして報告する。 許容している既存の負債によって、新規項目の登録基準を弱めない。 必要なcredentialが利用できる場合に限ってparserを実行する。 ローカルpreviewでは、既存の構造化データセットまたは文書化された直接解析のfallbackをsite generatorに使わせる。 ## 指定された投稿だけを見て、一覧に重複がないか確かめる レビュー対象を、ユーザーが指定した投稿に限定する。 pull requestの操作には、無関係なcommand-line clientではなく、設定済みのrepository connectorを使う。 変更操作の前に次を行う。 1. 提案されたファイルと差分を調べる。 2. カテゴリーの配置と正確な項目形式を確認する。 3. 正本の目録で重複を検索する。 4. 安全なURL形式を確認する。 5. 現在のproject activityとdocumentationを根拠に基づいて評価する。 6. 外部状態を変更する前に指摘事項を提示する。 開かれているという理由だけで、指定外の投稿をレビューしない。 提出された説明だけから人気度や保守状況を推測しない。 目録形式への適合と、リソースの品質・継続的な有用性を区別する。 ## プルリクエストへのコメントや取り込みの前に、必ず聞く pull requestへのcomment、label付与、close、mergeの前には、必ずユーザーへ確認する。 ユーザーがreview commentを承認した後に限り、review完了labelを付ける。 そのmergeに対する明示的な承認後に限り、mergeする。 接続済みrepository toolを使って、開いているrequestの一覧、詳細、ファイル、comment、label、差分を確認し、重複確認用にdefault branchの目録を取得し、承認済みの変更を実行する。 必要なconnectorが利用できない場合に、別の外部toolで代用しない。 connectorがなければrepository操作が停止していると報告し、設定をユーザーへ依頼する。 読み取り専用の根拠収集と、外部状態の変更を分ける。 レビューの指示だけでは、comment、label、close、mergeは承認されていない。 ## アクセス用のキーを隠し、サイトは決まった自動の手順でだけ公開する 外部メタデータの補足を、credentialが必要な操作として扱う。 必要なaccess credentialなしに実行せず、command、report、生成ページ、commit対象ファイルへcredentialを決して露出しない。 公開工程を再現可能に保つ。 - 正本の目録を解析し、文書化された構造化データセットへ変換する。 - ローカルpreviewでは、文書化されたfallbackだけを使う。 - 現在の検証済み入力から静的ページを生成する。 - 設定済みのcontinuous-integration workflowだけを通して公開する。 - parserまたはtemplateの挙動が変わった場合は、生成差分をレビューする。 ローカルpreviewだけを根拠に、公開成功を主張しない。 生成成果物と公開workflowを個別に検証する。 ## 確かめた範囲を書き、新しいエラーと前からある注意を分けて報告する レビューした投稿、指摘事項、検証モード、停止中の操作を報告する。 確認範囲が新規項目だけか、目録全体かを明示する。 既存内容に由来するwarningと、今回の変更が持ち込んだerrorを分けて示す。 完了前に次を確認する。 - 目録が正本のまま維持された。 - 項目文法、句読記号、tag、category、安全なURLを確認した。 - 現在のdefault branchを基準に重複を確認した。 - activityとdocumentationに関する主張が根拠に基づいている。 - 承認なしに外部状態を変更していない。 - 生成成果物を正本のsource contentと取り違えていない。 判断に必要な簡潔さを保ちつつ、登録可否を変えうる指摘はすべて含める。