Ultralytics オープンソースプロジェクトへの貢献
ようこそ! Ultralytics オープンソースプロジェクトへの貢献をご検討いただきありがとうございます。皆様の関与は、当社のリポジトリの品質を向上させるだけでなく、コンピュータビジョンコミュニティ全体にも利益をもたらします。このガイドでは、開始にあたって役立つ明確なガイドラインとベストプラクティスを提供します。
見る: Ultralyticsリポジトリへの貢献方法 | Ultralyticsモデル、データセット、ドキュメント 🚀
🤝 行動規範
すべての人にとって歓迎的でインクルーシブな環境を確保するために、すべての貢献者は行動規範を遵守する必要があります。尊敬、親切、そしてプロ意識は、私たちのコミュニティの中心です。
🚀 プルリクエストによる貢献
プルリクエスト(PR)の形式での貢献に大変感謝いたします。レビュープロセスをできるだけスムーズにするために、次の手順に従ってください。
- Fork the repository: 関連するUltralyticsリポジトリ(例:ultralytics/ultralytics)をあなたのGitHubアカウントにフォークすることから始めましょう。
- ブランチを作成: 変更内容を明確に反映したわかりやすい名前(例:
fix-issue-123
,add-feature-xyz
)。 - 変更を加える: 改善または修正を実装します。コードがプロジェクトのスタイルガイドラインに準拠し、新しいエラーや警告が発生しないようにしてください。
- 変更をテストする: 送信する前に、変更をローカルでテストして、期待どおりに動作すること、およびリグレッションが発生しないことを確認してください。新しい機能を追加する場合は、テストを追加してください。
- 変更をコミット: 簡潔で説明的なコミットメッセージで変更をコミットしてください。変更が特定の問題に対処する場合は、問題番号を含めてください(例:
Fix #123: Corrected calculation error.
)。 - プルリクエストを作成: あなたのブランチからプルリクエストを送信してください。
main
元のUltralyticsリポジトリのブランチ。変更の目的と範囲を説明する明確なタイトルと詳細な説明を提供してください。
📝 CLA署名
プルリクエストをマージする前に、Contributor License Agreement (CLA)に署名する必要があります。この法的合意により、あなたの貢献が適切にライセンスされ、プロジェクトがAGPL-3.0 licenseの下で配布され続けることが保証されます。
プルリクエストを送信すると、CLAボットが署名プロセスを案内します。CLAに署名するには、PRに次のコメントを追加するだけです。
I have read the CLA Document and I sign the CLA
✍️ Googleスタイルのドキュメンテーション
新しい関数やクラスを追加する際は、以下を含めてください。 Googleスタイルのドキュメンテーション文字列 明確で標準化されたドキュメントのために、常に入力と出力の両方を囲んでください。 types
括弧内(例: (bool)
, (np.ndarray)
)。
ドキュメンテーション文字列の例
この例は、標準的なGoogleスタイルのドキュメンテーション文字列の形式を示しています。関数説明、引数、戻り値、および例が最大限に読みやすくなるように明確に分離されていることに注意してください。
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
この例では、名前付きの戻り変数をドキュメント化する方法を示します。名前付きの戻り値を使用すると、特に複雑な関数では、コードの自己文書化が進み、理解しやすくなります。
def example_function(arg1, arg2=4):
"""
Example function demonstrating Google-style docstrings.
Args:
arg1 (int): The first argument.
arg2 (int): The second argument.
Returns:
equals (bool): True if arguments are equal, False otherwise.
Examples:
>>> example_function(4, 4) # True
"""
equals = arg1 == arg2
return equals
この例では、複数の値を返す関数をドキュメント化する方法を示します。明確にするために、各戻り値は、独自の型と説明で個別にドキュメント化する必要があります。
def example_function(arg1, arg2=4):
"""
Example function demonstrating Google-style docstrings.
Args:
arg1 (int): The first argument.
arg2 (int): The second argument.
Returns:
equals (bool): True if arguments are equal, False otherwise.
added (int): Sum of both input arguments.
Examples:
>>> equals, added = example_function(2, 2) # True, 4
"""
equals = arg1 == arg2
added = arg1 + arg2
return equals, added
注:pythonは複数の値をタプルとして返しますが(例: return masks, scores
) は、明確さとツールとの連携を向上させるために、常に各値を個別に記述してください。複数の値を返す関数を記述する場合は、
✅ 良い例 - 各戻り値を個別にドキュメント化:
Returns:
(np.ndarray): Predicted masks with shape HxWxN.
(list): Confidence scores for each instance.
❌ 悪い例 - ネストされた要素を持つタプルとしてドキュメント化しないでください:
Returns:
(tuple): Tuple containing:
- (np.ndarray): Predicted masks with shape HxWxN.
- (list): Confidence scores for each instance.
この例では、Googleスタイルのドキュメンテーション文字列とPythonの型ヒントを組み合わせています。型ヒントを使用する場合、関数シグネチャで型がすでに指定されているため、ドキュメンテーション文字列の引数セクションの型情報を省略できます。
def example_function(arg1: int, arg2: int = 4) -> bool:
"""
Example function demonstrating Google-style docstrings.
Args:
arg1: The first argument.
arg2: The second argument.
Returns:
True if arguments are equal, False otherwise.
Examples:
>>> example_function(1, 1) # True
"""
return arg1 == arg2
より小さく、より単純な機能には、1行のドキュメンテーション文字列で十分な場合があります。これらは、大文字で始まりピリオドで終わる、簡潔でありながら完全な文である必要があります。
def example_small_function(arg1: int, arg2: int = 4) -> bool:
"""Example function with a single-line docstring."""
return arg1 == arg2
✅ GitHub Actions CIテスト
すべてのプルリクエストは、マージされる前にGitHub Actionsの継続的インテグレーション(CI)テストに合格する必要があります。これらのテストには、lint処理、ユニットテスト、および変更がプロジェクトの品質基準を満たしていることを確認するためのその他のチェックが含まれます。CIの出力を確認し、発生した問題に対処してください。
✨ コード貢献のためのベストプラクティス
Ultralyticsプロジェクトにコードを投稿する際は、以下のベストプラクティスを念頭に置いてください。
- コードの重複を避ける: 可能な限り既存のコードを再利用し、不要な引数を最小限に抑えます。
- より小規模で、焦点を絞った変更を加える: 大規模な変更ではなく、対象を絞った修正に焦点を当てます。
- 可能な限り簡素化する: コードを簡素化したり、不要な部分を削除したりする機会を探します。
- 互換性を考慮する: 変更を加える前に、Ultralyticsを使用している既存のコードを壊す可能性があるかどうかを検討してください。
- 一貫性のあるフォーマットを使用する: Ruff Formatterのようなツールは、スタイルの統一性を維持するのに役立ちます。
- 適切なテストの追加: 新機能が期待どおりに動作することを確認するために、テストを含めます。
👀 プルリクエストのレビュー
プルリクエストのレビューも、貢献する上で非常に有益な方法です。PRをレビューする際は、以下に留意してください。
- 単体テストの確認: PRに新機能または変更のテストが含まれていることを確認します。
- ドキュメントの更新レビュー: 変更を反映するためにドキュメントが更新されていることを確認します。
- パフォーマンスへの影響を評価する: 変更がパフォーマンスにどのように影響するかを検討してください。
- CIテストの確認: すべての継続的インテグレーションテストが合格していることを確認します。
- 建設的なフィードバックを提供してください: 問題や懸念事項について、具体的で明確なフィードバックを提供してください。
- 努力を認識する: ポジティブな協力的な雰囲気を維持するために、著者の業績を認めましょう。
🐞 バグの報告
バグレポートは、プロジェクトの品質と信頼性を向上させるのに役立つため、非常に重要です。GitHub Issuesからバグを報告する場合は、以下に従ってください。
- 既存のissueを確認: まず検索して、バグがすでに報告されているかどうかを確認してください。
- 最小限の再現可能な例を提供してください: 問題を一貫して再現する、小さく自己完結型のコードスニペットを作成します。 これは、効率的なデバッグに不可欠です。
- 環境について説明します: オペレーティングシステム、pythonバージョン、関連ライブラリのバージョン(例:
torch
,ultralytics
)、およびハードウェア(CPU/GPU)。 - 期待される動作と実際の動作の説明: 期待される結果と実際に発生した結果を明確に記述してください。エラーメッセージやトレースバックも記載してください。
📜 ライセンス
Ultralyticsは、リポジトリにGNU Affero General Public License v3.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ライセンスの下で公開することを意味します。
-
開始点を選択してください:
- Ultralytics YOLOをフォーク: Ultralytics YOLOリポジトリを直接フォークして、その上に密接に構築します。
- Ultralyticsテンプレートの使用: YOLOを統合するためのクリーンでモジュール化されたセットアップには、Ultralyticsテンプレートリポジトリから始めてください。
-
プロジェクトのライセンス:
- 追加
LICENSE
の全文を含むファイル AGPL-3.0ライセンス. - 各ソースファイルの先頭に、ライセンスを示す通知を追加します。
- 追加
-
ソースコードの公開:
- あなただけの プロジェクト全体のソースコード 一般公開されているもの(例:GitHub)。これには以下が含まれます。
- YOLOモデルまたはコードを組み込んだ、より大規模なアプリケーションまたはシステム全体。
- オリジナルのUltralytics YOLOコードに加えられた変更。
- トレーニング、検証、推論用のスクリプト。
- 変更または微調整された場合のモデルの重み。
- 設定ファイル、環境設定(
requirements.txt
,Dockerfiles
)。 - ウェブアプリケーションの一部である場合のバックエンドおよびフロントエンドコード。
- 変更したサードパーティライブラリ。
- トレーニングデータは、実行/再トレーニングに必要であり、再配布可能です。
- あなただけの プロジェクト全体のソースコード 一般公開されているもの(例:GitHub)。これには以下が含まれます。
-
明確なドキュメント:
- あなたの
README.md
プロジェクトがAGPL-3.0に基づいてライセンスされていることを示します。 - ソースコードからプロジェクトをセットアップ、ビルド、および実行する方法に関する明確な指示を含めます。
- 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のオープンソースリポジトリに貢献すべきなのはなぜですか?
Ultralytics YOLO オープンソースリポジトリに貢献することで、ソフトウェアが改善され、コミュニティ全体にとってより堅牢で機能が豊富になります。貢献には、コードの拡張、バグ修正、ドキュメントの改善、および新機能の実装が含まれます。さらに、貢献することで、その分野の他の熟練した開発者や専門家と協力し、自身のスキルと評判を高めることができます。開始方法の詳細については、プルリクエストによる貢献セクションを参照してください。
Ultralytics YOLO のコントリビューターライセンス契約(CLA)に署名するにはどうすればよいですか?
貢献者ライセンス契約(CLA)に署名するには、プルリクエストを送信した後、CLAボットから提供される指示に従ってください。このプロセスにより、あなたの貢献がAGPL-3.0ライセンスの下で適切にライセンスされ、オープンソースプロジェクトの法的完全性が維持されます。プルリクエストにコメントを追加して、以下のように述べてください。
I have read the CLA Document and I sign the CLA
詳細については、CLA署名のセクションをご覧ください。
Googleスタイルのドキュメント文字列とは何ですか?また、Ultralytics YOLOへの貢献に必須なのはなぜですか?
Googleスタイルのdocstringは、関数とクラスに関する明確で簡潔なドキュメントを提供し、コードの可読性と保守性を向上させます。これらのdocstringは、特定の書式ルールを用いて、関数の目的、引数、および戻り値を概説します。Ultralytics YOLOに貢献する際は、Googleスタイルのdocstringに従うことで、追加されたコードが適切に文書化され、理解しやすくなります。例とガイドラインについては、GoogleスタイルのDocstringsのセクションをご覧ください。
変更がGitHub Actions CIテストに合格することを保証するにはどうすればよいですか?
プルリクエストをマージするには、すべてのGitHub Actions Continuous Integration (CI)テストに合格する必要があります。これらのテストには、lint処理、ユニットテスト、およびコードがプロジェクトの品質基準を満たしていることを確認するためのその他のチェックが含まれます。CIの出力を確認し、問題を修正してください。CIプロセスとトラブルシューティングのヒントの詳細については、GitHub Actions CI Testsセクションを参照してください。
Ultralytics YOLO リポジトリのバグを報告するにはどうすればよいですか?
バグを報告するには、明確で簡潔な最小再現可能事例をバグレポートとともに提供してください。これにより、開発者は問題を迅速に特定して修正できます。問題の再現に必要最小限の例であることを確認してください。バグ報告の詳細な手順については、バグの報告セクションを参照してください。
Ultralytics YOLOを自分のプロジェクトで使用する場合、AGPL-3.0ライセンスはどういう意味を持ちますか?
Ultralytics YOLOのコードまたはモデル(AGPL-3.0ライセンス)をプロジェクトで使用する場合、AGPL-3.0ライセンスでは、プロジェクト全体(派生物)もAGPL-3.0ライセンスの下でライセンスされ、その完全なソースコードを公開する必要があります。これにより、ソフトウェアのオープンソース性がその派生物全体で維持されます。これらの要件を満たせない場合は、エンタープライズライセンスを取得する必要があります。詳細については、プロジェクトのオープンソース化セクションを参照してください。