docs: add org-wide CONTRIBUTING.md#92
Conversation
Org-wide default contribution guide in smkwlab/.github (applies to repos without their own). Covers the conventions actually used across the DNS/Elixir ecosystem: branch strategy (feature branch, no direct main commits), commit messages (Conventional Commits, English, issue number), PR flow (green CI, squash merge, up-to-date-branch ruleset on .github), Lefthook test/lint (format -> test -> credo --strict), the reusable CI matrix (LTS + latest), and dependency updates via Renovate. Elixir-specific parts are labelled since the org spans LaTeX / competitive-programming repos too. Addresses the ecosystem CLAUDE.md doc TODO #4. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JPuooHgsrboSEbfJsNf6iG
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| 各リポは `smkwlab/.github` の再利用ワークフローを `@v1` で呼び出す: | ||
|
|
||
| - **`elixir-ci.yml`** — Code Quality（format/credo）＋ **OTP/Elixir マトリクス（LTS + latest の2組）** でのテスト。coverage（Codecov）・Dialyzer も含む。 | ||
| - 具体的な OTP/Elixir 版は各 caller が渡す（源泉は caller の workflow）。現行は概ね **LTS = OTP 27 系 / Elixir 1.17 系**、**latest = OTP 29 系 / Elixir 1.20 系**。 |
There was a problem hiding this comment.
🚨 [HIGH] 行 53 の OTP/Elixir バージョン情報について：
現行は概ね LTS = OTP 27 系 / Elixir 1.17 系、latest = OTP 29 系 / Elixir 1.20 系
Elixir 1.20 は 2025年7月時点でまだリリースされていません（最新は 1.18 系）。latest の具体的なバージョンをドキュメントに固定すると、実態と乖離した際に誤解を招きます。バージョンは caller workflow の定義が正とする旨のみ記載し、具体的な数字は削除するか、「各 caller の workflow を参照」と書くにとどめることを推奨します。
There was a problem hiding this comment.
対応しました（具体的な版数を削除し「caller 定義が正／CI ジョブ名で確認」に変更）。なお前提のご指摘は誤りで、Elixir 1.20.1 は既にリリース済みです（本 org の CI ジョブ「Test on OTP 29.0.2 / Elixir 1.20.1」が実際に緑で走っています）。レビューモデルの知識カットオフ由来の誤指摘ですが、バージョン直書きはドリフトの元なので削除自体は妥当と判断し反映しました。
| - AI 支援で作成したコミットは、末尾に共同作者トレーラを付ける慣行: | ||
| ``` | ||
| Co-Authored-By: <AI モデル名> <noreply@anthropic.com> | ||
| ``` |
There was a problem hiding this comment.
Co-Authored-By: <AI モデル名> <noreply@anthropic.com>
この形式は Anthropic（Claude）固有です。GitHub Copilot や OpenAI 系ツールを使う場合はメールアドレスが異なります（例: noreply@github.com）。org 内で複数の AI ツールを使う可能性があるなら、「使用した AI ツールのガイドラインに従う」と汎用的に記載するか、ツールごとの例を列挙する方が正確です。
There was a problem hiding this comment.
対応しました。Anthropic 固有にならないよう「使用ツールの規約に従う」と一般化し、Renovate（renovate[bot]）と Claude の例を併記しました。
| 3. **すべての CI チェックが green** になること（下記「CI」参照）。 | ||
| 4. レビュー指摘は、**盲信も却下もせず**、docs / 実コード / 実機動作で裏取りしてから対応する。恒常的でない LOW 指摘は根拠を添えて in-thread 返信で収束させてよい。 | ||
| 5. マージは原則 **squash merge**。マージ後は作業ブランチを削除する。 | ||
| - `smkwlab/.github` は **up-to-date-branch ルールセット**があるため、`main` が先行した PR は先にブランチ更新（`gh api -X PUT repos/OWNER/REPO/pulls/N/update-branch`）してからマージする。 |
There was a problem hiding this comment.
ℹ️ [LOW] 行 32 の gh api コマンドについて：
gh api -X PUT repos/OWNER/REPO/pulls/N/update-branch
この GitHub REST API エンドポイントは PUT ではなく PUT で正しいですが、実際には gh pr update-branch <PR番号> という gh CLI のサブコマンドが存在し、より簡潔です。raw API を使う理由がなければ gh pr update-branch を案内する方が利用者にとって分かりやすいです。
There was a problem hiding this comment.
gh pr update-branch <PR> を第一案として追記し、REST 直叩きを fallback にしました。補足: 現行 org の gh（toshi0806）には gh pr update-branch サブコマンドが無いため（実測で確認済み、エコシステム CLAUDE.md にも記録）、そのバージョンでは REST が実際に効く経路です。両対応にしています。
…s, note gh pr update-branch - Co-Authored-By guidance made tool-agnostic (not Anthropic-specific). - Remove the concrete LTS/latest OTP/Elixir numbers; point to the caller workflow + the live CI job names (avoids doc drift). - update-branch: mention `gh pr update-branch` with the REST fallback. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JPuooHgsrboSEbfJsNf6iG
|
|
||
| ## ライセンス | ||
|
|
||
| ライセンスはリポジトリごとに異なる（例: `tdig` は BSD 3-Clause）。各リポの `LICENSE` を確認すること。貢献した内容は当該リポジトリのライセンス下で提供したものとみなす。 |
There was a problem hiding this comment.
| 1. feature ブランチを push し、`main` 宛に PR を作成する。 | ||
| 2. PR 本文に **何を・なぜ** を書く。Issue を閉じる場合は `resolve #<番号>` を含める（tracking issue など閉じたくない場合は `Refs #<番号>` にする）。 | ||
| 3. **すべての CI チェックが green** になること（下記「CI」参照）。 | ||
| 4. レビュー指摘は、**盲信も却下もせず**、docs / 実コード / 実機動作で裏取りしてから対応する。恒常的でない LOW 指摘は根拠を添えて in-thread 返信で収束させてよい。 |
There was a problem hiding this comment.
ℹ️ [LOW] 「恒常的でない LOW 指摘は根拠を添えて in-thread 返信で収束させてよい」という記述は、レビュー指摘の扱いとして曖昧さが残ります。「恒常的でない」の定義が不明確で、貢献者によって解釈が異なる可能性があります。例えば「一時的な実装上の制約による LOW 指摘」など、より具体的な条件を示すか、あるいはシンプルに「LOW 指摘は根拠を添えて返信し、レビュアーと合意の上で収束させてよい」とした方が誤解が少ないと思われます。
| 各リポは `smkwlab/.github` の再利用ワークフローを `@v1` で呼び出す: | ||
|
|
||
| - **`elixir-ci.yml`** — Code Quality（format/credo）＋ **OTP/Elixir マトリクス（LTS + latest の2組）** でのテスト。coverage（Codecov）・Dialyzer も含む。 | ||
| - 具体的な OTP/Elixir 版は各 caller の workflow が渡す（**正は caller の定義**）。実際に使われている版は各リポの CI ジョブ名「Test on OTP … / Elixir …」で確認できる。 |
There was a problem hiding this comment.
ℹ️ [LOW] 「正は caller の定義」という表現は日本語として不自然で、意味が取りにくいです。「正式な定義は caller の workflow を参照」や「実際に使用されるバージョンは各リポの caller workflow で定義される」のように書き換えると読みやすくなります。
There was a problem hiding this comment.
対応しました。「版の定義元は caller 側の workflow」に言い換えて明確化しました。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JPuooHgsrboSEbfJsNf6iG
|
|
||
| 下川研究室（smkwlab）org のリポジトリ共通の貢献ガイドです。**このファイルは org 全体のデフォルト**で、個別リポに `CONTRIBUTING.md` が無い場合に GitHub が自動適用します（Issue / PR 作成時の「Contributing」リンク）。個別リポに固有ルールがある場合はそのリポの `CONTRIBUTING.md` / `README.md` / `CLAUDE.md` が優先します。 | ||
|
|
||
| 以下のうち **Elixir リポ限定**の項目は明記します（DNS/Elixir 群: `tenbin_dns` / `tdig` / `tenbin_ex` / `tenbin_cache` / `elixir_dnstap`）。LaTeX・競技プログラミング等のリポは該当部を読み替えてください。 |
There was a problem hiding this comment.
tenbin_dns / tdig / tenbin_ex / tenbin_cache / elixir_dnstap）をハードコードしています。リポが追加・削除された際にこのリストが陳腐化するリスクがあります。具体的なリポ名を列挙するよりも、「DNS/Elixir 系リポ（各リポの README.md 参照）」のように抽象化するか、メンテナンス責任を明記しておくと将来の混乱を防げます。
| - AI / bot 支援で作成したコミットは、その旨を `Co-Authored-By:` トレーラで明示する慣行。メールアドレス等は**使用したツールの規約に従う**（例: Renovate は `renovate[bot] <…@users.noreply.github.com>`、Claude は Anthropic の指定アドレス）: | ||
| ``` | ||
| Co-Authored-By: <ツール / モデル名> <ツールが指定するアドレス> | ||
| ``` |
There was a problem hiding this comment.
ℹ️ [LOW] 行 20–23 の AI / bot 支援コミットに関する記述で、Co-Authored-By: トレーラのフォーマット例が <ツール / モデル名> <アドレス> となっており、Co-Authored-By: の後に名前とメールアドレスが必要な Git の標準フォーマット（Co-Authored-By: Name <email>）と一致しています。ただし、コードブロック内の例が抽象的すぎて、実際にどう書けばよいか分かりにくい可能性があります。Renovate や Claude の具体例を1行ずつ示すと、貢献者が迷わず使えます。
例:
Co-Authored-By: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>
| 3. **すべての CI チェックが green** になること（下記「CI」参照）。 | ||
| 4. レビュー指摘は、**盲信も却下もせず**、docs / 実コード / 実機動作で裏取りしてから対応する。恒常的でない LOW 指摘は根拠を添えて in-thread 返信で収束させてよい。 | ||
| 5. マージは原則 **squash merge**。マージ後は作業ブランチを削除する。 | ||
| - `smkwlab/.github` は **up-to-date-branch ルールセット**があるため、`main` が先行した PR は先にブランチ更新してからマージする（`gh pr update-branch <PR番号>`、未対応の gh バージョンなら `gh api -X PUT repos/OWNER/REPO/pulls/N/update-branch`）。 |
There was a problem hiding this comment.
ℹ️ [LOW] 行 32 の gh api -X PUT repos/OWNER/REPO/pulls/N/update-branch は、実際の GitHub REST API エンドポイントが PUT /repos/{owner}/{repo}/pulls/{pull_number}/update-branch であり、N を {pull_number} に置き換える必要があることが分かりにくいです。OWNER/REPO/N をプレースホルダとして明示するか、gh pr update-branch が使えない場合の代替として git fetch origin main && git rebase origin/main も選択肢として示すと実用的です。
1 participant
Org 全体のデフォルト貢献ガイド（
smkwlab/.githubroot のCONTRIBUTING.md）。個別リポにCONTRIBUTING.mdが無い場合に GitHub が自動適用します。実際にエコシステムで使われている慣行を記載（invent せず裏取り済み）:
main直接 commit 禁止、issue-<番号>-<内容>命名chore(deps):/docs(scope):に準拠）.githubの up-to-date-branch ルールセット対応format → test → credo --strict、LEFTHOOK=0skipelixir-ci/security/ai-review、OTP/Elixir は LTS+latest マトリクスorg は LaTeX/競プロ repo も併存するため Elixir 固有部は明示。エコシステム CLAUDE.md の doc TODO #4 に対応。
🤖 Generated with Claude Code