Beitrag leisten zu Ultralytics Open-Source-Projekten

Willkommen! Wir freuen uns sehr, dass du einen Beitrag zu unseren Ultralytics Open-Source Projekten leisten möchtest. Dein Engagement hilft nicht nur dabei, die Qualität unserer Repositories zu verbessern, sondern kommt auch der gesamten Computer Vision Community zugute. Dieser Leitfaden bietet klare Richtlinien und Best Practices, die dir den Einstieg erleichtern.

🤝 Verhaltenskodex

Um eine einladende und integrative Umgebung für alle zu gewährleisten, müssen sich alle Mitwirkenden an unseren Verhaltenskodex halten. Respekt, Freundlichkeit und Professionalität stehen im Mittelpunkt unserer Community.

🚀 Mitwirken über Pull Requests

Wir wissen Beiträge in Form von Pull Requests (PRs) sehr zu schätzen. Um den Review-Prozess so reibungslos wie möglich zu gestalten, befolge bitte diese Schritte:

1. Repository forken: Beginne damit, das entsprechende Ultralytics Repository (z. B. ultralytics/ultralytics) auf dein GitHub-Konto zu forken.
2. Branch erstellen: Erstelle einen neuen Branch in deinem geforkten Repository mit einem klaren, beschreibenden Namen, der deine Änderungen widerspiegelt (z. B. fix-issue-123, add-feature-xyz).
3. Änderungen vornehmen: Implementiere deine Verbesserungen oder Korrekturen. Stelle sicher, dass dein Code den Stilrichtlinien des Projekts entspricht und keine neuen Fehler oder Warnungen einführt.
4. Änderungen testen: Teste deine Änderungen vor dem Einreichen lokal, um sicherzustellen, dass sie wie erwartet funktionieren und keine Regressionen verursachen. Füge Tests hinzu, wenn du neue Funktionen einführst.
5. Änderungen committen: Committe deine Änderungen mit prägnanten und aussagekräftigen Commit-Nachrichten. Wenn deine Änderungen ein bestimmtes Problem beheben, gib die Issue-Nummer an (z. B. Fix #123: Corrected calculation error.).
6. Pull Request erstellen: Reiche einen Pull Request von deinem Branch an den main Branch des ursprünglichen Ultralytics Repositories ein. Gib einen klaren Titel und eine detaillierte Beschreibung an, die Zweck und Umfang deiner Änderungen erläutert.

📝 CLA unterzeichnen

Bevor wir deinen Pull Request mergen können, musst du unser Contributor License Agreement (CLA) unterzeichnen. Diese rechtliche Vereinbarung stellt sicher, dass deine Beiträge ordnungsgemäß lizenziert sind, sodass das Projekt weiterhin unter der AGPL-3.0 license vertrieben werden kann.

Nach dem Einreichen deines Pull Requests führt dich der CLA-Bot durch den Unterzeichnungsprozess. Um die CLA zu unterzeichnen, kommentiere einfach deinen PR mit folgendem Satz:

✍️ Google-Style Docstrings

Wenn du neue Funktionen oder Klassen hinzufügst, verwende Google-style docstrings für eine klare, standardisierte Dokumentation. Schließe sowohl Eingabe- als auch Ausgabe-types immer in Klammern ein (z. B. (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-Tests

Alle Pull Requests müssen die GitHub Actions Continuous Integration (CI)-Tests bestehen, bevor sie gemergt werden können. Diese Tests umfassen Linting, Unit-Tests und andere Prüfungen, um sicherzustellen, dass deine Änderungen den Qualitätsstandards des Projekts entsprechen. Überprüfe die CI-Ausgabe und behebe auftretende Probleme.

✨ Best Practices für Code-Beiträge

Wenn du Code zu Ultralytics-Projekten beisteuerst, beachte diese Best Practices:

• Code-Duplizierung vermeiden: Nutze bestehenden Code so weit wie möglich wieder und minimiere unnötige Argumente.
• Kleinere, fokussierte Änderungen vornehmen: Konzentriere dich auf gezielte Anpassungen statt auf groß angelegte Änderungen.
• Vereinfachen, wenn möglich: Suche nach Möglichkeiten, den Code zu vereinfachen oder unnötige Teile zu entfernen.
• Kompatibilität berücksichtigen: Überlege vor Änderungen, ob diese bestehenden Code, der Ultralytics verwendet, beeinträchtigen könnten.
• Einheitliche Formatierung verwenden: Tools wie Ruff Formatter können dabei helfen, die stilistische Konsistenz zu wahren.
• Angemessene Tests hinzufügen: Füge Tests für neue Funktionen hinzu, um sicherzustellen, dass sie wie erwartet funktionieren.

👀 Pull Requests überprüfen

Das Reviewen von Pull Requests ist eine weitere wertvolle Art, einen Beitrag zu leisten. Beim Reviewen von PRs:

• Auf Unit-Tests prüfen: Überprüfe, ob der PR Tests für neue Funktionen oder Änderungen enthält.
• Dokumentationsupdates prüfen: Stelle sicher, dass die Dokumentation aktualisiert wurde, um Änderungen widerzuspiegeln.
• Leistungsauswirkungen bewerten: Überlege, wie sich Änderungen auf die Leistung auswirken könnten.
• CI-Tests verifizieren: Bestätige, dass alle Continuous Integration-Tests erfolgreich sind.
• Konstruktives Feedback geben: Biete spezifisches, klares Feedback zu eventuellen Problemen oder Bedenken.
• Aufwand anerkennen: Würdige die Arbeit des Autors, um eine positive, kollaborative Atmosphäre zu wahren.

🐞 Fehler melden

Wir schätzen Fehlerberichte sehr, da sie uns helfen, die Qualität und Zuverlässigkeit unserer Projekte zu verbessern. Wenn du einen Fehler über GitHub Issues meldest:

• Bestehende Issues prüfen: Suche zuerst, ob der Fehler bereits gemeldet wurde.
• Ein Minimum Reproducible Example bereitstellen: Erstelle einen kleinen, in sich geschlossenen Code-Schnipsel, der das Problem konsistent reproduziert. Dies ist entscheidend für ein effizientes Debugging.
• Umgebung beschreiben: Gib dein Betriebssystem, die Python-Version, relevante Bibliotheksversionen (z. B. torch, ultralytics) und die Hardware (CPU/GPU) an.
• Erwartetes vs. tatsächliches Verhalten erklären: Gib klar an, was du erwartet hast und was tatsächlich passiert ist. Füge Fehlermeldungen oder Tracebacks bei.

📜 Lizenz

Ultralytics verwendet die GNU Affero General Public License v3.0 (AGPL-3.0) für seine Repositories. Diese Lizenz fördert Offenheit, Transparenz und kollaborative Verbesserung in der Softwareentwicklung. Sie stellt sicher, dass alle Benutzer die Freiheit haben, die Software zu nutzen, zu modifizieren und zu teilen, was eine starke Community der Zusammenarbeit und Innovation fördert.

Wir ermutigen alle Mitwirkenden, sich mit den Bedingungen der AGPL-3.0 license vertraut zu machen, um effektiv und ethisch zur Ultralytics Open-Source-Community beizutragen.

🌍 Dein YOLO-Projekt unter AGPL-3.0 Open-Sourcing

Verwendest du Ultralytics YOLO-Modelle oder -Code in deinem Projekt? Die AGPL-3.0 license erfordert, dass dein gesamtes abgeleitetes Werk ebenfalls unter der AGPL-3.0 Open Source gestellt wird. Dies stellt sicher, dass Modifikationen und größere Projekte, die auf Open-Source-Grundlagen aufbauen, offen bleiben.

Warum die Einhaltung der AGPL-3.0 wichtig ist

• Hält Software offen: Stellt sicher, dass Verbesserungen und abgeleitete Werke der Community zugutekommen.
• Rechtliche Anforderung: Die Verwendung von unter AGPL-3.0 lizenziertem Code bindet dein Projekt an dessen Bedingungen.
• Fördert Zusammenarbeit: Ermutigt zu Austausch und Transparenz.

Wenn du dein Projekt lieber nicht als Open Source veröffentlichen möchtest, ziehe den Erwerb einer Enterprise License in Betracht.

So hältst du die AGPL-3.0 ein

Die Einhaltung bedeutet, den vollständigen entsprechenden Quellcode deines Projekts unter der AGPL-3.0 Lizenz öffentlich verfügbar zu machen.

1. Wähle deinen Ausgangspunkt:

   • Ultralytics YOLO forken: Forke direkt das Ultralytics YOLO repository, wenn du eng darauf aufbaust.
   • Ultralytics Template verwenden: Beginne mit dem Ultralytics template repository für ein sauberes, modulares Setup, das YOLO integriert.

2. Lizenziere dein Projekt:

   • Füge eine LICENSE-Datei hinzu, die den vollständigen Text der AGPL-3.0 license enthält.
   • Füge einen Hinweis oben in jeder Quelldatei hinzu, der die Lizenz angibt.

3. Veröffentliche deinen Quellcode:

   • Mache den Quellcode deines gesamten Projekts öffentlich zugänglich (z. B. auf GitHub). Dies beinhaltet:
     • Die vollständige größere Anwendung oder das System, das das YOLO-Modell oder den Code enthält.
     • Alle Modifikationen, die am ursprünglichen Ultralytics YOLO-Code vorgenommen wurden.
     • Skripte für Training, Validierung und Inferenz.
     • Model weights, sofern sie modifiziert oder feinabgestimmt wurden.
     • Konfigurationsdateien, Umgebungssetups (requirements.txt, Dockerfiles).
     • Backend- und Frontend-Code, falls Teil einer Webanwendung.
     • Alle Drittanbieter-Bibliotheken, die du modifiziert hast.
     • Trainingsdaten, falls erforderlich für das Ausführen/Nachtraining und weiterverbreitbar.

4. Klar dokumentieren:

   • Aktualisiere deine README.md, um anzugeben, dass das Projekt unter der AGPL-3.0 lizenziert ist.
   • Füge klare Anweisungen bei, wie dein Projekt aus dem Quellcode eingerichtet, erstellt und ausgeführt werden kann.
   • Nenne Ultralytics YOLO angemessen und verlinke zurück zum ursprünglichen Repository. Beispiel:

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

Beispiel-Struktur des Repositorys

Siehe das Ultralytics Template Repository für eine praktische Beispielstruktur:

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

Durch Befolgen dieser Richtlinien stellst du die Einhaltung der AGPL-3.0 sicher und unterstützt das Open-Source-Ökosystem, das leistungsstarke Tools wie Ultralytics YOLO erst ermöglicht.

Fazit

Vielen Dank für dein Interesse, einen Beitrag zu Ultralytics Open-Source YOLO-Projekten zu leisten. Deine Teilnahme ist entscheidend, um die Zukunft unserer Software zu gestalten und eine lebendige Community der Innovation und Zusammenarbeit aufzubauen. Egal, ob du Code verbesserst, Fehler meldest oder neue Funktionen vorschlägst – deine Beiträge sind von unschätzbarem Wert.

Wir sind gespannt, deine Ideen zum Leben zu erwecken und schätzen dein Engagement für den Fortschritt der Objekterkennungstechnologie. Lass uns gemeinsam auf dieser spannenden Open-Source-Reise weiter wachsen und innovativ sein.

FAQ

Warum sollte ich zu den Ultralytics YOLO Open-Source-Repositories beitragen?

Beiträge zu den Ultralytics YOLO Open-Source-Repositories verbessern die Software und machen sie für die gesamte Community robuster und funktionsreicher. Beiträge können Code-Erweiterungen, Fehlerbehebungen, Verbesserungen der Dokumentation und neue Funktionsimplementierungen umfassen. Außerdem ermöglicht dir die Mitarbeit die Zusammenarbeit mit anderen qualifizierten Entwicklern und Experten auf diesem Gebiet, was deine eigenen Fähigkeiten und deinen Ruf verbessert. Details zum Einstieg findest du im Abschnitt Mitwirken über Pull Requests.

Wie unterzeichne ich das Contributor License Agreement (CLA) für Ultralytics YOLO?

Um das Contributor License Agreement (CLA) zu unterzeichnen, befolge die Anweisungen, die der CLA-Bot nach dem Einreichen deines Pull Requests bereitstellt. Dieser Prozess stellt sicher, dass deine Beiträge ordnungsgemäß unter der AGPL-3.0 Lizenz lizenziert sind und bewahrt die rechtliche Integrität des Open-Source-Projekts. Kommentiere deinen Pull Request mit folgendem Text:

Weitere Informationen findest du im Abschnitt CLA Signing.

Was sind Google-Style Docstrings und warum sind sie für Beiträge zu Ultralytics YOLO erforderlich?

Google-Style Docstrings bieten eine klare, prägnante Dokumentation für Funktionen und Klassen und verbessern so die Lesbarkeit und Wartbarkeit des Codes. Diese Docstrings skizzieren den Zweck, die Argumente und die Rückgabewerte der Funktion mit spezifischen Formatierungsregeln. Wenn du zu Ultralytics YOLO beiträgst, stellt die Einhaltung der Google-Style Docstrings sicher, dass deine Erweiterungen gut dokumentiert und leicht verständlich sind. Beispiele und Richtlinien findest du im Abschnitt Google-Style Docstrings.

Wie kann ich sicherstellen, dass meine Änderungen die GitHub Actions CI-Tests bestehen?

Bevor dein Pull Request zusammengeführt werden kann, muss er alle GitHub Actions Continuous Integration (CI)-Tests bestehen. Diese Tests umfassen Linting, Unit-Tests und weitere Prüfungen, um sicherzustellen, dass der Code den Qualitätsstandards des Projekts entspricht. Überprüfe die CI-Ausgabe und behebe etwaige Probleme. Detaillierte Informationen zum CI-Prozess und Tipps zur Fehlerbehebung findest du im Abschnitt GitHub Actions CI Tests.

Wie melde ich einen Fehler in Ultralytics YOLO Repositories?

Um einen Fehler zu melden, stelle zusammen mit deinem Fehlerbericht ein klares und präzises Minimum Reproducible Example bereit. Dies hilft den Entwicklern, das Problem schnell zu identifizieren und zu beheben. Stelle sicher, dass dein Beispiel minimal, aber ausreichend ist, um das Problem zu reproduzieren. Weitere detaillierte Schritte zur Fehlerberichterstattung findest du im Abschnitt Reporting Bugs.

Was bedeutet die AGPL-3.0-Lizenz, wenn ich Ultralytics YOLO in meinem eigenen Projekt verwende?

Wenn du Ultralytics YOLO Code oder Modelle (lizenziert unter AGPL-3.0) in deinem Projekt verwendest, schreibt die AGPL-3.0-Lizenz vor, dass auch dein gesamtes Projekt (das abgeleitete Werk) unter AGPL-3.0 lizenziert sein muss und dessen vollständiger Quellcode öffentlich zugänglich gemacht werden muss. Dies stellt sicher, dass der Open-Source-Charakter der Software in ihren Ableitungen gewahrt bleibt. Falls du diese Anforderungen nicht erfüllen kannst, musst du eine Enterprise License erwerben. Weitere Details findest du im Abschnitt Open-Sourcing Your Project.