はじめる

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

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

Ultralyticsのオープンソース貢献者



視聴: 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))。

Docstringの例

この例では、標準的なGoogleスタイルのdocstring形式を示します。読みやすさを高めるため、関数の説明、引数、戻り値、例が明確に分けられている点に注目してください。

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をレビューする際は、次の点を確認してください。

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

バグの報告#

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

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

ライセンス#

Ultralyticsのリポジトリには、GNU Affero一般公衆利用許諾書 バージョン3.0(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. 開始方法を選ぶ:

  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プロジェクトへのコントリビューションに関心をお寄せいただき、ありがとうございます。コードの改善、バグの報告、新機能の提案など、皆様の参加がソフトウェアとコミュニティの発展につながります。

物体検出技術の発展にご尽力いただき、ありがとうございます。皆様のコントリビューションをお待ちしています。

よくある質問#

  • Ultralytics YOLOのオープンソースリポジトリへの貢献は、ソフトウェアを改善し、コミュニティ全体にとってより堅牢で機能豊富なものにします。貢献には、コードの改善、バグ修正、ドキュメントの改善、新機能の実装などがあります。また、熟練した開発者やその分野の専門家と協力することで、自身のスキルや評判を高めることもできます。始め方については、プルリクエストによる貢献のセクションを参照してください。

  • コントリビューターライセンス契約(CLA)に署名するには、プルリクエストの送信後にCLA botから提示される手順に従ってください。この手続きにより、貢献内容がAGPL-3.0ライセンスの下で適切にライセンスされ、オープンソースプロジェクトの法的整合性が保たれます。プルリクエストに次のコメントを追加してください。

    I have read the CLA Document and I sign the CLA

    詳細については、CLAへの署名のセクションを参照してください。

  • Googleスタイルのdocstringは、関数やクラスの明確で簡潔なドキュメントを提供し、コードの可読性と保守性を高めます。関数の目的、引数、戻り値を、定められた書式ルールに沿って記述します。Ultralytics YOLOへの貢献でGoogleスタイルのdocstringに従うと、追加したコードが適切に文書化され、理解しやすくなります。例とガイドラインについては、Googleスタイルのdocstringのセクションを参照してください。

  • プルリクエストをマージするには、すべてのGitHub Actionsの継続的インテグレーション(CI)テストに合格する必要があります。これらのテストには、リンティング、単体テスト、その他のチェックが含まれ、コードがプロジェクトの品質基準を満たしていることを確認します。CIの出力を確認し、問題があれば修正してください。CIのプロセスとトラブルシューティングのヒントについて詳しくは、GitHub ActionsのCIテストのセクションを参照してください。

  • バグを報告するには、明確で簡潔な最小再現可能な例をバグ報告に添えてください。これにより、開発者が問題を迅速に特定して修正できます。例は、問題を再現するのに十分な内容を保ちながら、最小限にしてください。バグ報告の詳しい手順については、バグの報告のセクションを参照してください。

  • プロジェクトでUltralytics YOLOのコードやモデル(AGPL-3.0ライセンス)を使用する場合、AGPL-3.0ライセンスにより、プロジェクト全体(派生物)もAGPL-3.0の下でライセンスし、完全なソースコードを公開する必要があります。これにより、派生物全体でソフトウェアのオープンソース性が保たれます。これらの要件を満たせない場合は、エンタープライズライセンスを取得する必要があります。詳細については、プロジェクトのオープンソース化のセクションを参照してください。

コメント7

質問したり、結果を共有したり、ほかの人をサポートしたりできます。

  1. Mehrab-ShahbaziGitHub

    Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).

    1. Mehrab-ShahbaziGitHub

      by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)

    2. Glenn JocherUltralytics

      @Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.

  2. esssyjrGitHub

    Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.

    1. Glenn JocherUltralytics

      @esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including train/ and val/ folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.

    2. esssyjrGitHub

      Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU