Beitrag zu Ultralytics Open-Source-Projekten#

Willkommen! Wir freuen uns sehr, dass du in Erwägung ziehst, zu unseren Ultralytics Open-Source-Projekten beizutragen. Dein Engagement trägt nicht nur dazu bei, die Qualität unserer Repositories zu verbessern, sondern kommt auch der gesamten Computer Vision-Community zugute. Dieser Leitfaden bietet klare Richtlinien und bewährte Methoden, um dir den Einstieg zu erleichtern.

🤝 Verhaltenskodex#

Um eine einladende und inklusive 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.

🚀 Beitrag über Pull Requests#

Wir schätzen Beiträge in Form von Pull Requests (PRs) sehr. Damit der Überprüfungsprozess so reibungslos wie möglich verläuft, befolge bitte die folgenden Schritte:

1. Repository forken: Beginne damit, das relevante Ultralytics Repository (z. B. ultralytics/ultralytics) auf dein GitHub-Konto zu forken.
2. Einen Branch erstellen: Erstelle einen neuen Branch in deinem geforkten Repository mit einem klaren, aussagekräftigen Namen, der deine Änderungen widerspiegelt (z. B. fix-issue-123, add-feature-xyz).
3. Nimm deine Änderungen vor: Implementiere deine Verbesserungen oder Korrekturen. Stelle sicher, dass dein Code den Style-Richtlinien des Projekts entspricht und keine neuen Fehler oder Warnungen einführt.
4. Teste deine Änderungen: 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. Deine Änderungen committen: Committe deine Änderungen mit prägnanten und aussagekräftigen Commit-Nachrichten. Wenn sich deine Änderungen auf ein bestimmtes Problem beziehen, gib die Issue-Nummer an (z. B. Fix #123: Corrected calculation error.).
6. Einen Pull Request erstellen: Reiche einen Pull Request von deinem Branch an den Branch main des ursprünglichen Ultralytics Repository ein. Gib einen klaren Titel und eine detaillierte Beschreibung an, die den Zweck und den Umfang deiner Änderungen erläutert.

📚 Dokumentationsänderungen#

Die Dokumentationsquelle befindet sich unter docs/en/. Installiere im Stammverzeichnis des Repositorys die Entwicklungsabhängigkeiten und führe die vollständige strenge Validierung aus, bevor du einen PR öffnest:

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

Die Validierung bereitet generierte Referenzen, Makros und Vergleichsseiten vor, bevor zensical build --strict ausgeführt wird. Für eine schnellere Live-Vorschau von Seiten, die keine Makros verwenden, führe zensical serve aus.

📝 CLA-Unterzeichnung#

Bevor wir deinen Pull Request zusammenführen können, musst du unsere 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-Lizenz vertrieben werden kann.

Nach dem Einreichen deines Pull Requests wird dich der CLA-Bot durch den Unterzeichnungsprozess führen. Um das CLA zu unterzeichnen, füge einfach einen Kommentar in deinem PR hinzu:

I have read the CLA Document and I sign the CLA

✍️ Google-Style Docstrings#

Füge beim Hinzufügen neuer Funktionen oder Klassen Google-Style Docstrings für eine klare, standardisierte Dokumentation hinzu. Setze sowohl Ein- als auch Ausgaben types immer in Klammern (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-Tests (CI) bestehen, bevor sie zusammengeführt 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 beiträgst, beachte diese Best Practices:

• Vermeide Codeduplizierung: Verwende vorhandenen Code wo immer möglich wieder und minimiere unnötige Argumente.
• Nimm kleinere, fokussierte Änderungen vor: Konzentriere dich auf gezielte Anpassungen statt auf großflächige Änderungen.
• Vereinfache, wo möglich: Suche nach Möglichkeiten, den Code zu vereinfachen oder unnötige Teile zu entfernen.
• Berücksichtige Kompatibilität: Überlege vor Änderungen, ob diese vorhandenen Code, der Ultralytics verwendet, beschädigen könnten.
• Verwende ein konsistentes Format: Tools wie der Ruff Formatter können dabei helfen, die stilistische Konsistenz aufrechtzuerhalten.
• Füge passende Tests hinzu: Füge Tests für neue Funktionen hinzu, um sicherzustellen, dass sie wie erwartet funktionieren.

👀 Pull Requests prüfen#

Das Prüfen von Pull Requests ist eine weitere wertvolle Form des Beitrags. Beim Prüfen von PRs:

• Auf Unit-Tests prüfen: Verifiziere, dass der PR Tests für neue Funktionen oder Änderungen enthält.
• Überprüfe Dokumentationsaktualisierungen: Stelle sicher, dass die Dokumentation aktualisiert wird, um Änderungen widerzuspiegeln.
• Leistungs auswirkungen 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 Problemen oder Bedenken.
• Aufwand anerkennen: Würdige die Arbeit des Autors, um eine positive, kollaborative Atmosphäre zu wahren.

🐞 Bugs melden#

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

• Existierende Issues prüfen: Suche zuerst, ob der Bug bereits gemeldet wurde.
• Stelle ein Minimal Reproducible Example bereit: Erstelle einen kleinen, in sich geschlossenen Code-Snippet, der das Problem konsistent reproduziert. Dies ist entscheidend für ein effizientes Debugging.
• Beschreibe die Umgebung: Gib dein Betriebssystem, deine Python-Version, relevante Bibliotheksversionen (z. B. torch, ultralytics) und die Hardware (CPU/GPU) an.
• Erkläre erwartetes vs. tatsächliches Verhalten: Gib klar an, was du erwartet hast und was tatsächlich passiert ist. Füge alle 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, und fördert eine starke Community der Zusammenarbeit und Innovation.

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

🌍 Open-Source-Veröffentlichung deines YOLO-Projekts unter AGPL-3.0#

Verwendest du Ultralytics YOLO-Modelle oder Code in deinem Projekt? Die AGPL-3.0-Lizenz verlangt, 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 AGPL-3.0-Konformität wichtig ist#

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

Wenn du es vorziehst, dein Projekt nicht als Open Source zu veröffentlichen, ziehe den Erwerb einer Enterprise License in Betracht.

So erfüllst du die Anforderungen der AGPL-3.0#

Konformität bedeutet, den vollständigen korrespondierenden Quellcode deines Projekts öffentlich unter der AGPL-3.0-Lizenz zur Verfügung zu stellen.

1. Wähle deinen Startpunkt:

   • Forke Ultralytics YOLO: Forke das Ultralytics YOLO Repository direkt, wenn du eng darauf aufbaust.
   • Verwende die Ultralytics-Vorlage: 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-Lizenz enthält.
   • Füge am Anfang jeder Quelldatei einen Hinweis hinzu, der auf die Lizenz hinweist.

3. Veröffentliche deinen Quellcode:

   • Mache den Quellcode deines gesamten Projekts öffentlich zugänglich (z. B. auf GitHub). Dies umfasst:
     • Die vollständige größere Anwendung oder das System, das das YOLO-Modell oder den Code einbindet.
     • Alle Modifikationen, die am ursprünglichen Ultralytics YOLO-Code vorgenommen wurden.
     • Skripte für Training, Validierung und Inferenz.
     • Modellgewichte, falls modifiziert oder fine-getuned.
     • Konfigurationsdateien, Umgebungssetups (requirements.txt, Dockerfiles).
     • Backend- und Frontend-Code, wenn er Teil einer Webanwendung ist.
     • Alle Bibliotheken von Drittanbietern, die du modifiziert hast.
     • Trainingsdaten, sofern zum Ausführen/Retrainieren erforderlich und weiterverbreitbar.

4. Dokumentiere klar:

   • Aktualisiere deine README.md, um anzugeben, dass das Projekt unter der AGPL-3.0 lizenziert ist.
   • Füge klare Anweisungen hinzu, wie dein Projekt aus dem Quellcode eingerichtet, gebaut und ausgeführt wird.
   • Verleihe Ultralytics YOLO die entsprechende Namensnennung und verlinke auf das ursprüngliche Repository. Beispiel:

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

Beispiel-Repository-Struktur#

Beziehe dich auf das Ultralytics Template Repository für eine praktische Beispiestruktur:

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

Indem du diese Richtlinien befolgst, stellst du die Konformität mit der AGPL-3.0 sicher und unterstützt das Open-Source-Ökosystem, das leistungsstarke Tools wie Ultralytics YOLO ermöglicht.

Fazit#

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

Wir freuen uns darauf, deine Ideen zum Leben zu erwecken, und schätzen dein Engagement für die Weiterentwicklung der Objekterkennung-Technologie. Lass uns gemeinsam auf dieser spannenden Open-Source-Reise weiter wachsen und innovativ sein.

FAQ#