Ultralyticsのオープンソースプロジェクトへの貢献について#

ようこそ！Ultralyticsのオープンソースプロジェクトへの貢献をご検討いただき、大変嬉しく思います。皆様のご参加は、リポジトリの品質向上に役立つだけでなく、コンピュータビジョンコミュニティ全体に利益をもたらします。このガイドでは、スムーズに開発に参加できるよう、明確なガイドラインとベストプラクティスを提供します。

🤝 行動規範#

すべての人にとって歓迎され、包括的な環境を確保するため、すべての貢献者はCode of Conductを遵守する必要があります。尊重、親切心、そしてプロ意識は、私たちのコミュニティの中心にあります。

🚀 プルリクエスト（PR）を通じた貢献#

pull requests (PRs)の形式での貢献に深く感謝いたします。レビュープロセスをできる限り円滑に進めるため、以下の手順に従ってください。

1. リポジトリをフォークする: 関連するUltralyticsのリポジトリ（例：ultralytics/ultralytics）をご自身のGitHubアカウントにフォークすることから始めます。
2. ブランチを作成する: 変更内容を明確に表す分かりやすい名前（例：fix-issue-123、add-feature-xyz）を付けて、フォークしたリポジトリに新しいブランチを作成します。
3. 変更を加える: 改善点や修正を実装します。コードがプロジェクトのスタイルガイドラインに準拠していること、また新たなエラーや警告を引き起こさないことを確認してください。
4. 変更をテストする: 送信する前に、変更をローカルでテストし、期待どおりに動作すること、およびリグレッションを引き起こさないことを確認してください。新しい機能を追加する場合は、テストを追加してください。
5. 変更をコミットする: 簡潔で分かりやすいコミットメッセージをつけて変更をコミットします。変更が特定の問題に対処している場合は、issue番号を含めてください（例：Fix #123: Corrected calculation error.）。
6. プルリクエストを作成する: ご自身のブランチから、元のUltralyticsリポジトリの main ブランチへプルリクエストを送信します。変更の目的と範囲を説明する、明確なタイトルと詳細な説明文を提供してください。

📚 ドキュメントの変更#

ドキュメントのソースは docs/en/ の下にあります。リポジトリのルートから開発依存関係をインストールし、PRを開く前に完全な厳密バリデーションを実行してください：

uv pip install -e ".[dev]"
python docs/build_docs.py

バリデーションは、zensical build --strict を実行する前に、生成されるリファレンス、マクロ、比較ページを準備します。マクロを使用しないページのより高速なライブプレビューを行うには、zensical serve を実行してください。

📝 CLAへの署名#

プルリクエストをマージする前に、Contributor License Agreement (CLA)に署名する必要があります。この法的合意により、貢献物が適切にライセンスされ、プロジェクトが引き続きAGPL-3.0 licenseのもとで配布されることが保証されます。

プルリクエスト送信後、CLAボットが署名プロセスを案内します。CLAに署名するには、PRに以下のコメントを追加するだけです。

I have read the CLA Document and I sign the CLA

✍️ GoogleスタイルのDocstring#

新しい関数やクラスを追加する場合は、明確で標準化されたドキュメントを作成するためにGoogle-style docstringsを含めてください。入力と出力の両方の types を常に括弧で囲んでください（例：(bool)、(np.ndarray)）。

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

✅ GitHub Actions CIテスト#

すべてのプルリクエストは、マージされる前にGitHub ActionsContinuous Integration（CI）テストに合格する必要があります。これらのテストには、リンティング、単体テスト、および変更がプロジェクトの品質基準を満たしていることを確認するためのその他のチェックが含まれます。CIの出力を確認し、発生した問題に対処してください。

✨ コード貢献のベストプラクティス#

Ultralyticsプロジェクトにコードを貢献する際は、以下のベストプラクティスを考慮してください。

• コードの重複を避ける: 可能な限り既存のコードを再利用し、不要な引数を最小限に抑えてください。
• 小さく的を絞った変更を行う: 大規模な変更よりも、ターゲットを絞った修正に注力してください。
• 可能な場合は単純化する: コードを簡素化したり、不要な部分を削除したりする機会がないか検討してください。
• 互換性を考慮する: 変更を加える前に、それらが既存のUltralyticsコードに悪影響を及ぼさないか検討してください。
• 一貫したフォーマットを使用する: Ruff Formatterなどのツールは、スタイルの統一性を維持するのに役立ちます。
• 適切なテストを追加する: 新機能が期待どおりに動作することを確認するためにテストを含めてください。

👀 プルリクエストのレビュー#

プルリクエストのレビューも、貢献の貴重な手段の一つです。PRをレビューする際は、以下の点を確認してください。

• ユニットテストの確認: PRに新機能や変更に対するテストが含まれているか検証します。
• ドキュメントの更新を確認する: 変更を反映するようにドキュメントが更新されていることを確認してください。
• パフォーマンスへの影響を評価する: 変更がパフォーマンスにどのように影響するかを検討してください。
• CIテストを検証する: すべてのContinuous Integration testsが合格していることを確認してください。
• 建設的なフィードバックを提供する: 問題点や懸念事項について、具体的かつ明確なフィードバックを行います。
• 努力を称える: 良好な協力関係を維持するため、著者の取り組みを認めます。

🐞 バグ報告#

バグレポートはプロジェクトの品質と信頼性を向上させるのに役立つため、非常に重視しています。GitHub Issuesを介してバグを報告する場合:

• 既存のIssueを確認する: そのバグが既に報告されていないか、まず検索してください。
• Minimum Reproducible Exampleを提供する: 問題を常に再現する、小さく自己完結型のコードスニペットを作成します。これは効率的なデバッグに不可欠です。
• 環境を説明する: オペレーティングシステム、Pythonバージョン、関連するライブラリバージョン（例：torch、ultralytics）、およびハードウェア（CPU/GPU）を指定してください。
• 期待される動作と実際の動作を説明する: 何を期待していたのか、そして実際に何が起こったのかを明確に述べてください。エラーメッセージやトレースバックも必ず含めてください。

📜 ライセンス#

Ultralyticsは、そのリポジトリにGNU Affero General Public License v3.0 (AGPL-3.0)を使用しています。このライセンスは、ソフトウェア開発における開放性、透明性、および協調的改善を促進します。すべてのユーザーがソフトウェアを使用、変更、共有する自由を持つことを保証し、コラボレーションとイノベーションの強力なコミュニティを育成します。

すべての貢献者が、Ultralyticsオープンソースコミュニティに効果的かつ倫理的に貢献するために、AGPL-3.0 licenseの条件に精通することを推奨します。

🌍 YOLOプロジェクトをAGPL-3.0の下でオープンソース化する#

プロジェクトでUltralytics YOLOのモデルやコードを使用していますか？AGPL-3.0 licenseでは、派生物全体もAGPL-3.0の下でオープンソース化することが義務付けられています。これにより、オープンソースの基盤上に構築された変更や大規模なプロジェクトがオープンな状態を維持できるようになります。

AGPL-3.0のコンプライアンスが重要な理由#

• ソフトウェアをオープンに保つ: 改善点や派生した成果物がコミュニティの利益になることを保証します。
• 法的な要件: AGPL-3.0ライセンスコードの使用は、あなたのプロジェクトをその条項に拘束します。
• コラボレーションを促進する: 共有と透明性を奨励します。

プロジェクトをオープンソースにしたくない場合は、Enterprise Licenseの取得をご検討ください。

AGPL-3.0に準拠する方法#

準拠とは、プロジェクトの対応する完全なソースコードをAGPL-3.0ライセンスの下で公開することを意味します。

1. 開始点を選択する:

   • Ultralytics YOLOをフォークする: 密接にベースにして構築する場合は、Ultralytics YOLO repositoryを直接フォークします。
   • Ultralyticsテンプレートを使用する: YOLOを統合したクリーンでモジュール式のセットアップのために、Ultralytics template repositoryから始めます。

2. プロジェクトをライセンスする:

   • AGPL-3.0ライセンスの全文を含む LICENSE ファイルを追加してください。
   • 各ソースファイルの先頭に、ライセンスを示す通知を追加してください。

3. ソースコードを公開する:

   • プロジェクト全体のソースコードを一般公開してください（例: GitHub上）。これには以下が含まれます。
     • YOLOモデルやコードを取り込んだ、完全な大規模アプリケーションやシステム。
     • 元のUltralytics YOLOコードに加えられたいかなる変更。
     • 学習、検証、推論のためのスクリプト。
     • 変更または微調整された場合のModel weights。
     • Configuration files、環境設定（requirements.txt、Dockerfiles）。
     • web applicationの一部である場合のバックエンドおよびフロントエンドコード。
     • 変更したすべてのthird-party libraries。
     • 実行/再トレーニングに必要であり、かつ再配布可能なTraining data。

4. 明確にドキュメント化する:

   • プロジェクトがAGPL-3.0の下でライセンスされていることを明記するように、README.md を更新します。
   • ソースコードからプロジェクトをセットアップ、ビルド、実行する方法についての明確な手順を含めてください。
   • original repositoryへのリンクを貼り付けて、Ultralytics YOLOを適切にクレジット表記します。例:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

リポジトリ構造の例#

実際の例の構造については、Ultralytics Template Repositoryを参照してください:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

これらのガイドラインに従うことで、AGPL-3.0への準拠を確保し、Ultralytics YOLOのような強力なツールを可能にするオープンソースのエコシステムを支援することになります。

結論#

Ultralyticsのopen-source YOLOプロジェクトへの貢献にご関心をお持ちいただきありがとうございます。皆様のご参加は、ソフトウェアの未来を形作り、イノベーションとコラボレーションの活気あるコミュニティを築くために不可欠です。コードの機能向上、バグの報告、新機能の提案など、どのような形であれ、皆様の貢献はかけがえのないものです。

皆様のアイデアが形になるのを楽しみにしています。また、object detection技術の発展に対する皆様の取り組みに感謝いたします。このエキサイティングなオープンソースの旅において、共に成長し革新を続けましょう。

よくある質問 (FAQ)#