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

ようこそ！Ultralyticsのオープンソースプロジェクトへの貢献をご検討いただき、ありがとうございます。皆さまの参加は、リポジトリの品質向上に役立つだけでなく、コンピュータービジョンコミュニティ全体にも貢献します。このガイドでは、貢献を始める際に役立つ明確なガイドラインとベストプラクティスを紹介します。

行動規範#

誰もが安心して参加できるインクルーシブな環境を実現するため、すべての貢献者は行動規範を遵守する必要があります。敬意、親切さ、プロ意識は、コミュニティの中心にあります。

プルリクエストによる貢献#

プルリクエスト（PRs）による貢献を歓迎します。レビューをできるだけ円滑に進めるため、次の手順に従ってください。

1. リポジトリをフォークする： まず、該当するUltralyticsリポジトリ（例：ultralytics/ultralytics）を自分のGitHubアカウントにフォークします。
2. ブランチを作成する： フォークしたリポジトリに、変更内容がわかる明確で説明的な名前のブランチを作成します（例：fix-issue-123、add-feature-xyz）。
3. 変更を加える： 改善や修正を実装します。プロジェクトのスタイルガイドラインに従い、新たなエラーや警告が発生しないことを確認してください。
4. 変更をテストする： 送信前にローカルで変更をテストし、想定どおりに動作することと、リグレッションが発生しないことを確認してください。新しい機能を追加する場合は、テストも追加してください。
5. 変更をコミットする： 簡潔でわかりやすいコミットメッセージを付けて変更をコミットします。特定のIssueに対応する変更の場合は、Issue番号を記載してください（例：Fix #123: Corrected calculation error.）。
6. プルリクエストを作成する： ブランチから元のUltralyticsリポジトリのmainブランチにプルリクエストを送信します。変更の目的と範囲を説明する、明確なタイトルと詳細な説明を記載してください。

開発環境のインストール#

フォーク（またはメインリポジトリ）をクローンし、編集可能モード（-e）でインストールします。これにより、再インストールせずにPythonでローカルファイルを実行し、変更をすべて反映できます。

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

別のプロジェクトでPyPIパッケージの代わりにフォークを依存先として使用するには、pipまたはrequirements.txtの参照先をフォークのブランチに設定します。

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

ドキュメントの変更#

ドキュメントのソースはdocs/en/以下にあります。PRを作成する前に、リポジトリのルートから開発用依存関係をインストールし、厳密な検証をすべて実行してください。

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

検証では、zensical build --strictを実行する前に、生成されたリファレンス、マクロ、比較ページを準備します。マクロを使用しないページをすばやくライブプレビューするには、zensical serveを実行します。

CLAへの署名#

プルリクエストをマージする前に、貢献者ライセンス契約（CLA）に署名する必要があります。この法的契約により、貢献内容が適切にライセンスされ、プロジェクトをAGPL-3.0ライセンスの下で引き続き配布できます。

プルリクエストを送信すると、CLAボットが署名手順を案内します。CLAに署名するには、PRに次のコメントを追加してください。

I have read the CLA Document and I sign the CLA

GoogleスタイルのDocstring#

新しい関数やクラスを追加する場合は、明確で標準化されたドキュメントにするため、Googleスタイルのdocstringを記述してください。入力と出力の両方の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 Actionsの継続的インテグレーション（CI）テストに合格する必要があります。これらのテストには、リンティング、ユニットテスト、その他のチェックが含まれ、変更がプロジェクトの品質基準を満たしていることを確認します。CIの出力を確認し、発生した問題に対処してください。

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

Ultralyticsプロジェクトにコードで貢献する際は、次のベストプラクティスを念頭に置いてください。

• コードの重複を避ける： 可能な限り既存のコードを再利用し、不要な引数を最小限に抑えます。
• 変更を小さく、焦点を絞る： 大規模な変更ではなく、対象を絞った修正を行います。
• 可能な限り簡素化する： コードを簡素化したり、不要な部分を削除したりできる箇所を探します。
• 互換性を考慮する： 変更を加える前に、Ultralyticsを使用する既存コードに影響する可能性があるか検討します。
• 一貫したフォーマットを使用する： Ruff Formatterなどのツールを使用すると、スタイルの一貫性を保ちやすくなります。
• 適切なテストを追加する： 新機能が想定どおりに動作することを確認するため、テストを追加します。

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

プルリクエストのレビューも、貴重な貢献方法のひとつです。PRをレビューする際は、次の点を確認してください。

• ユニットテストを確認する： PRに新機能や変更に対するテストが含まれていることを確認します。
• ドキュメントの更新を確認する： 変更内容が反映されるよう、ドキュメントが更新されていることを確認します。
• パフォーマンスへの影響を評価する： 変更がパフォーマンスに与える影響を検討します。
• CIテストを確認する： すべての継続的インテグレーションテストに合格していることを確認します。
• 建設的なフィードバックを提供する: 問題や懸念事項について、具体的で明確なフィードバックを伝えます。
• 努力を認める: 前向きで協力的な雰囲気を保つため、著者の取り組みを評価します。

バグの報告#

バグ報告はプロジェクトの品質と信頼性の向上に役立つため、非常に重視しています。GitHub Issuesからバグを報告する際は、次の点にご注意ください。

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

ライセンス#

Ultralyticsのリポジトリでは、GNU Affero一般公衆利用許諾書 第3版 (AGPL-3.0)を採用しています。このライセンスは、ソフトウェア開発におけるオープン性、透明性、共同での改善を促進します。すべてのユーザーにソフトウェアの使用、変更、共有の自由を保障し、協力とイノベーションの強固なコミュニティを育みます。

効果的かつ倫理的にUltralyticsのオープンソースコミュニティへ貢献できるよう、すべてのコントリビューターにAGPL-3.0ライセンスの条項をよく理解していただくことを推奨します。

AGPL-3.0に基づいてYOLOプロジェクトをオープンソース化する#

Ultralytics YOLOのモデルやコードをプロジェクトで使用していますか？AGPL-3.0ライセンスでは、派生物全体もAGPL-3.0に基づいてオープンソース化することが求められます。これにより、オープンソースを基盤として構築された変更や大規模なプロジェクトも、オープンな状態に保たれます。

AGPL-3.0への準拠が重要な理由#

• ソフトウェアをオープンに保つ: 改善や派生物がコミュニティに還元されるようにします。
• 法的要件: AGPL-3.0ライセンスのコードを使用すると、プロジェクトにもその条項が適用されます。
• コラボレーションを促進する: 共有と透明性を促します。

プロジェクトをオープンソース化しない場合は、エンタープライズライセンスの取得をご検討ください。

AGPL-3.0に準拠する方法#

準拠するには、プロジェクトの対応する完全なソースコードをAGPL-3.0ライセンスの下で公開する必要があります。

1. 開始方法を選ぶ:

   • Ultralytics YOLOをフォークする: Ultralytics YOLOをベースに開発する場合は、Ultralytics YOLOリポジトリを直接フォークします。
   • Ultralyticsのテンプレートを使用する: YOLOを統合した、シンプルでモジュール化された構成にするには、Ultralyticsテンプレートリポジトリから始めます。

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

   • AGPL-3.0ライセンスの全文を含むLICENSEファイルを追加します。
   • 各ソースファイルの先頭に、ライセンスを示す表記を追加します。

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

   • プロジェクト全体のソースコードを公開します（例: GitHub）。次のものが含まれます。
     • YOLOモデルまたはコードを組み込んだ、より大規模なアプリケーションやシステム全体。
     • 元のUltralytics YOLOコードに加えた変更。
     • トレーニング、検証、推論用のスクリプト。
     • 変更またはファインチューニングした場合は、モデルの重み。
     • 設定ファイル、環境構成（requirements.txt、Dockerfiles）。
     • Webアプリケーションの一部である場合は、バックエンドとフロントエンドのコード。
     • 変更を加えたサードパーティライブラリ。
     • 実行や再トレーニングに必要で、かつ再配布が許可されている場合は、トレーニングデータ。

4. 明確に文書化する:

   • プロジェクトがAGPL-3.0ライセンスであることを明記するよう、README.mdを更新します。
   • ソースコードからプロジェクトをセットアップ、ビルド、実行する方法を明確に記載します。
   • 元のリポジトリへのリンクを含め、Ultralytics YOLOを適切にクレジット表記します。例:

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

リポジトリ構成の例#

実用的な構成例については、Ultralyticsテンプレートリポジトリを参照してください。

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のオープンソースYOLOプロジェクトに関心をお寄せいただき、ありがとうございます。皆様の参加は、ソフトウェアの未来を形作り、イノベーションとコラボレーションに満ちた活気あるコミュニティを築くうえで欠かせません。コードの改善、バグの報告、新機能の提案など、皆様の貢献は非常に貴重です。

皆様のアイデアが実現することを楽しみにしています。また、物体検出技術の発展に取り組んでくださることに感謝します。このエキサイティングなオープンソースの取り組みを、ともに成長させ、革新を続けていきましょう。

よくある質問#