リポジトリの規約

これらの規則は、Luna-Flow のドキュメント標準を linear-algebra 向けに補うものです。マニュアルは現在のブランチの実装を記述し、現在の文書基準は 0.5.0 です。

ページと章

• 概要は現在のリリース基準、つまりリリースの内容、読み始める場所、各パッケージの位置づけを説明します。CHANGELOG.md は過去バージョンの時系列と古いリリースノートを担当します。
• 各パッケージは章ごとに 1 ページを持ち、そのパスにちなんで命名されます。api/immut.md は Matrix、Vector、MatrixFn をまとめて説明し、api/container/adapters.md は src/container/adapters を説明します。
• 内部パッケージとツール用パッケージ（internal、consistency、perf、perf_runner、perf_support）のページは短めで、役割と不変条件に焦点を当てています。
• 実行可能な例は moonbit check で囲まれ、すべてのページをリンクする src/doc_en_us のテストとしてコンパイルされます。例の中のトップレベル名はマニュアル全体で一意でなければなりません。ページ名を接頭辞として付けてください（たとえば mut_tut_）。
• integration/ 章では、外部の型が algebra と container の能力層に参加する方法を説明します。
• API 文書は仕様中心、tutorial は使い方中心、design は責務・境界・トレードオフ中心に書き分けます。
• バックエンドラッパーパッケージでは、プラットフォーム制約、変換境界、各挙動がローカル実装か外部ライブラリのカーネル委譲かを明記します。
• 冗長な言い回しやリリースノート調の文章を避け、短く直接的な技術文に寄せます。

mutable と immutable の共通規約

API 整合性の原則

• mutable と immutable は、可能な限り同じ公開 API を提供します。
• 両方のパッケージが同じ機能を持つ場合は、関数名、引数順、戻り値の意味、エラー規約を揃えることを優先します。
• 完全に揃えられない場合は、差分、理由、推奨される利用場面を文書で明示します。
• 新しい公開 API を追加するときは、原則として両方のパッケージで提供すべきかを検討します。

immutable パッケージの設計原則

• 関数型、宣言的、かつ合成しやすいインターフェース設計を優先します。
• 破壊的更新を露出するよりも、新しい値を返す形を優先します。
• 呼び出し側に隠れた状態、共有可変状態、タイミング依存の振る舞いを意識させないようにします。
• ドキュメントでは値セマンティクス、参照透過性、合成方法を重視して説明します。
• 性能上のトレードオフがある場合でも、まず外部セマンティクスの明確さと安定性を守ります。

mutable パッケージの設計原則

• 性能、メモリ再利用、低レベル実行効率を優先します。
• ライブラリ内部での可変状態、破壊的更新、その他の副作用は許容されます。
• ただし、それらの副作用は実装内部に閉じ込め、利用者のメンタルモデルへ漏らさないようにします。
• 公開 API は依然として純粋で安定しており、関数型の使い心地を保つべきです。内部の可変実装を契約として露出してはいけません。
• immutable と異なる専用 API は、性能上の利点が明確かつ必要な場合にのみ導入します。

ドキュメント記述要件

• mutable と immutable の API 文書では、可能な限り同じ節構成と用語を使います。
• 対応する API 同士を相互参照できるようにし、意味論とコストモデルを比較しやすくします。
• 外部セマンティクスと内部実装方針を明確に分けて記述します。
• キャッシュ、再利用、破壊的計算などの性能に関する詳細は、API の意味論的な契約ではなく、設計ページまたは performance/ 章に書きます。
• mutable 側で性能重視の設計により可観測な挙動差がある場合は、内部実装の説明だけで済ませず、その挙動を明示します。

翻訳

• 中国語訳は、英語の逐語訳ではなく、自然な書き言葉の技術中国語にします。
• 日本語訳は、中国語や英語の文型をそのまま写すのではなく、自然な技術文体の日本語にします。