ARCHITECTURE.md を追加しよう

• オープンソースへの参加を容易にするため、プロジェクトのアーキテクチャを説明するファイルをリポジトリに追加しようという内容

• ときどきプロジェクトに貢献する人とコア開発者の最大の違いは、プロジェクトのアーキテクチャに対する理解度

• 構造に慣れていないとパッチを書く時間も2倍以上かかるが、どこを直せばよいか場所を把握するのには10倍以上の時間がかかる

• 高水準のアーキテクチャを説明する ARCHITECTURE.md のようなファイルを作成

→ 短く書いて誰でも読めるようにし、あまり変更されない部分だけを整理する

→ コードと同期させようとせず、年に2回ほど見直す

内容の書き方

• 解決しようとしている問題の俯瞰図（Bird's eye view）から始める

• もう少し詳しいコードマップ: 「Xをするものはどこにありますか？」

• おおまかなモジュールとそれらの関係を説明する: 各モジュールが何をするかは別の文書へつなぐ

• 重要なファイル、モジュール、型の名前を書くこと

→ 読む人が名前で検索できるようにし、直接リンクはしないこと（リンク切れになる可能性があるため）

• レイヤーとシステム間の境界を明示する

• 良い例

• Rust Analyzer の Architecture.md - https://github.com/rust-analyzer/rust-analyzer/…

• Caddy Architecture : https://caddyserver.com/docs/architecture

[xguru]

そして、メインのREADME.mdに、できればプロジェクトの各フォルダについての説明も入れてほしいという意見もいいですね。

• https://news.ycombinator.com/item?id=26050082

例: https://github.com/diem/diem/…

できれば各フォルダに説明を入れて、GitHubがフォルダにREADMEがあればその内容を上位階層で表示してくれると、なおよさそうです。

関連して、Architecture Decision Records も参考にしてください。

• ADRを書くべき理由 https://ja.news.hada.io/topic?id=2665