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

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

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

🤝 行動規範

誰にとっても歓迎的で包括的な環境を維持するため、すべての貢献者は行動規範を遵守する必要があります。尊重、親切心、そしてプロフェッショナリズムが、私たちのコミュニティの核となります。

🚀 プルリクエストを通じた貢献

プルリクエスト (PR)による貢献を心より歓迎します。レビュープロセスを円滑に進めるため、以下の手順に従ってください：

リポジトリをフォークする： まず、関連するUltralyticsリポジトリ（例：ultralytics/ultralytics）を自分のGitHubアカウントにフォークします。
ブランチを作成する： フォークしたリポジトリ内に、変更内容を反映した明確で説明的な名前（例：fix-issue-123、add-feature-xyz）の新しいブランチを作成します。
変更を加える： 改善や修正を実装します。コードがプロジェクトのスタイルガイドラインに準拠していること、また新たなエラーや警告を引き起こさないことを確認してください。
変更をテストする： 送信前にローカルでテストを行い、意図した通りに動作し、リグレッションが発生しないことを確認します。新機能を追加する場合は、テストも追加してください。
Commit your changes: Commit your changes with concise and descriptive commit messages. If your changes address a specific issue, include the issue number (e.g., Fix #123: Corrected calculation error.).
プルリクエストを作成する： 自身のブランチから元のUltralyticsリポジトリのmainブランチに対してプルリクエストを送信します。変更の目的と範囲を説明するタイトルと詳細な説明を記載してください。

📝 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をレビューする際は：

ユニットテストを確認する： PRが新機能や変更に対するテストを含んでいるか検証します。
ドキュメントの更新を確認する： 変更内容を反映してドキュメントが更新されているかを確認します。
パフォーマンスへの影響を評価する： 変更がどのようにパフォーマンスに影響を与えるか考慮します。
CIテストを検証する： すべての継続的インテグレーションテストが通過していることを確認します。
建設的なフィードバックを提供する： 問題や懸念について、具体的で明確なフィードバックを提供します。
努力を称える： 前向きな協力関係を維持するために、作成者の作業を認めます。

🐞 バグ報告

バグ報告はプロジェクトの品質と信頼性を向上させるため、非常に大切にしています。GitHub Issues経由でバグを報告する際は：

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

📜 ライセンス

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

すべての貢献者がAGPL-3.0ライセンスの条項を把握し、Ultralyticsオープンソースコミュニティに対して効果的かつ倫理的に貢献することを推奨します。

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

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

なぜAGPL-3.0への準拠が重要なのか

ソフトウェアのオープン性を保つ： 改善や派生作品がコミュニティに還元されることを保証します。
法的要件： AGPL-3.0でライセンスされたコードを使用すると、プロジェクトはその条項に従う義務を負います。
コラボレーションを促進： 共有と透明性を奨励します。

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

AGPL-3.0への準拠方法

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

開始点を選択する：
- Ultralytics YOLOをフォークする： それを基に開発を進める場合は、直接Ultralytics YOLOリポジトリをフォークしてください。
- Ultralyticsテンプレートを使用する： YOLOを統合した、クリーンでモジュール化された設定のためにUltralyticsテンプレートリポジトリから始めてください。
プロジェクトをライセンスする：
- Add a LICENSE file containing the full text of the AGPL-3.0 license.
- 各ソースファイルの先頭に、ライセンスを示す注記を追加します。
ソースコードを公開する：
- プロジェクトのソースコード全体を（GitHubなどで）誰でもアクセスできるようにします。これには以下が含まれます：
  - YOLOモデルやコードを組み込んだ、より大きなアプリケーションやシステム全体。
  - 元のUltralytics YOLOコードに対して行った修正。
  - トレーニング、検証、および推論のためのスクリプト。
  - 修正またはファインチューニングされたモデル重み。
  - 設定ファイル、環境設定（requirements.txt、Dockerfiles）。
  - Webアプリケーションの一部である場合は、バックエンドおよびフロントエンドのコード。
  - 修正したすべてのサードパーティライブラリ。
  - 実行/再トレーニングに必要であり、かつ再配布可能な場合の学習データ。
明確にドキュメント化する：
- プロジェクトが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プロジェクトへの貢献に興味を持っていただきありがとうございます。皆様の参加は、私たちのソフトウェアの未来を形作り、イノベーションとコラボレーションの活気あるコミュニティを築く上で不可欠です。コードの改善、バグ報告、新機能の提案など、どのような形であれ、皆様の貢献はかけがえのないものです。

皆様のアイデアが形になることを楽しみにしています。また、物体検出技術の発展への貢献に感謝いたします。この素晴らしいオープンソースの旅路を、共に成長・革新していきましょう。

FAQ

なぜUltralytics YOLOのオープンソースリポジトリに貢献するべきですか？

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

Ultralytics YOLOの貢献者ライセンス同意書 (CLA) に署名するにはどうすればよいですか？

貢献者ライセンス同意書 (CLA) に署名するには、プルリクエストを送信した後にCLAボットから提供される指示に従ってください。このプロセスにより、あなたの貢献がAGPL-3.0ライセンスの下で適切にライセンスされ、オープンソースプロジェクトの法的な整合性が維持されます。プルリクエストに以下のコメントを追加してください：

I have read the CLA Document and I sign the CLA

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

GoogleスタイルDocstringとは何ですか？また、なぜUltralytics YOLOの貢献に必要なのですか？

GoogleスタイルDocstringは、関数やクラスに対して明快で簡潔なドキュメントを提供し、コードの読みやすさと保守性を向上させます。これらのDocstringは、関数の目的、引数、戻り値を特定の書式ルールで概説します。Ultralytics YOLOに貢献する際、GoogleスタイルDocstringに従うことで、あなたの追加コードが十分にドキュメント化され、容易に理解されるようになります。例やガイドラインについては、GoogleスタイルDocstringセクションをご覧ください。

自分の変更がGitHub Actions CIテストを確実に通過するようにするにはどうすればよいですか？

プルリクエストをマージする前に、すべてのGitHub Actions Continuous Integration (CI) テストに合格する必要があります。これらのテストには、コードがプロジェクトの品質基準を満たしていることを確認するためのリンティング、ユニットテスト、およびその他のチェックが含まれます。CIの出力を確認し、問題を修正してください。CIプロセスとトラブルシューティングのヒントに関する詳細については、GitHub Actions CI Testsセクションを参照してください。

Ultralytics YOLOリポジトリでバグを報告するにはどうすればよいですか？

バグを報告する際は、明確で簡潔なMinimum Reproducible Exampleをバグ報告と一緒に提供してください。これにより、開発者は問題を迅速に特定して修正できます。例は最小限でありながら、問題を再現するのに十分な内容であることを確認してください。バグ報告の手順の詳細については、Reporting Bugsセクションを参照してください。

自分のプロジェクトでUltralytics YOLOを使用する場合、AGPL-3.0ライセンスはどういう意味ですか？

プロジェクトでUltralytics YOLOのコードまたはモデル (AGPL-3.0ライセンス) を使用する場合、AGPL-3.0ライセンスでは、プロジェクト全体 (派生的著作物) もAGPL-3.0の下でライセンスされ、その完全なソースコードを公開することが義務付けられています。これにより、ソフトウェアのオープンソースとしての性質がその派生物全体を通じて維持されます。これらの要件を満たせない場合は、Enterprise Licenseを取得する必要があります。詳細については、Open-Sourcing Your Projectセクションを参照してください。

Contributors

GLglenn-jocher²² RIRizwanMunawar³ PDpderrenger¹ Y-Y-T-G¹WIWillie Maddox¹LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

Created 2023年11月12日Updated 先週