メインコンテンツまでスキップ

コーディング規約

このガイドは、SiMa.ai Neat ライブラリに組み込まれるコードに対する貢献ルールを定義します。

言語と API の制約​

  • C++20 を使用します。
  • 公開 API の変更は、意図的かつ最小限に抑えます（include/* は安定しているものとして扱います）。
  • 互換性を損なう変更よりも、後方互換性のある拡張を優先します。
  • 内部実装の詳細を、インストールされる/公開されるヘッダーから除外します。

フォーマットとスタイル​

  • C/C++ のフォーマットは、clang-format (.clang-format はリポジトリのルートにあります) を使用して強制します。
  • CMake のスタイルは、scripts/check_cmake_style.py によって強制されます。
  • C/C++ のソースコードにおける重複したインクルードは禁止します。
  • .editorconfig は、基本的な空白に関するルールを定義します（LF、最終行の改行、末尾の空白なし）。

プッシュする前に実行してください。

bash scripts/check_format.sh --changed-only
bash scripts/check_cmake_format.sh --changed-only
bash scripts/check_duplicate_includes.sh --changed-only

API互換性ポリシー​

include/*の下にインストールされているすべてのヘッダーについて、パブリックAPIの互換性は必須要件です。

  • 破壊的な変更を含まない追加が推奨されます（新しいオーバーロード、新しいオプションフィールド、新しいAPI）。
  • 破壊的なシグネチャの変更（名前の変更/削除/型の変更/パラメータの順序の変更/動作契約の破棄）は、マージ前にレビュープロセスを経る必要があります。
  • 破壊的な変更が避けられない場合は、まず段階的な廃止期間を設けることを推奨します（古いシグネチャを維持し、新しい代替手段を追加してから削除します）。

破壊的なAPIシグネチャに対する必須プロセス​

破壊的なAPIの変更をマージする前に：

  1. 変更内容を、専用のBreaking API ChangeセクションでPRの説明に記載します。
  2. 影響分析を含めます：影響を受けるヘッダー/シンボル、予想される下位互換性の問題、移行手順。
  3. バージョニング/リリース意図を含めます（変更がいつリリースされてもよいか）。
  4. 同じ変更セットで、ドキュメントとサンプルを新しいAPIに更新します。
  5. 破壊的なAPIの変更について、明確なメンテナーの承認を得ます。

モジュール境界​

依存関係ルールを厳密に守ります。

  • builder/は、GStreamerまたはpipeline/に依存してはなりません。
  • gst/は、pipeline/に依存してはなりません。
  • nodes/は、pipeline/に依存してはなりません。
  • pipeline/はオーケストレーターであり、gst/、builder/、nodes/、contracts/、policy/、およびモデルの内部構造に依存できます。

決定性要件​

  • ノードの出力は、等しい入力/構成に対して決定性でなければなりません。
  • 要素名は安定しており、再現可能に保ちます。
  • 可能な限り、決定的なパイプライン文字列の生成を維持します。
  • 名前付けの動作を変更する場合は、診断と検証によって要素がノードの所有権に正しくマッピングされるようにします。

エラー処理と診断​

  • 実行可能なコンテキストを持つ構造化されたエラーを優先します。
  • 新しいエラーパスには、PipelineReportの診断に必要な詳細が含まれていることを確認します。
  • プラグイン/キャップ/ランタイムエラーを隠蔽するサイレントなフォールバックは避けます。
  • 診断はスレッドセーフである必要があります。プローブ側の更新は、アトミックまたは同等のロックフリープリミティブを使用する必要があります。

並行性とライフサイクル​

  • 終了パスで無限にブロックすることは絶対に避けてください。
  • ランタイム状態の遷移を防御的に扱います（EOS、NULL、タイムアウトセーフな終了パス）。
  • ストリーミングスレッドのロジックは軽量で、副作用が制御されているようにします。

ドキュメントに関する義務​

動作が変更された場合：

  • アーキテクチャを更新します。
  • ワークフローまたはパラメータが変更された場合は、ユーザー向けのガイドを更新します。
  • 新しい環境変数をリファレンスドキュメントに記載します。

PRの品質基準​

貢献が完了したとみなされるのは、次のものが含まれている場合です。

  • コードとコミット/PRメッセージに明確な理由が記載されている。
  • 新しい動作と回帰に対するテストが含まれている。
  • ユーザーに表示される変更に対するドキュメントが更新されている。
  • パブリックヘッダーの変更に対するAPI互換性の評価（および該当する場合は、完全な破壊的変更プロセス）。