Zu Open-Source-Projekten von Ultralytics beitragen#

Willkommen! Wir freuen uns sehr, dass du erwägst, zu unseren Ultralytics-Open-Source-Projekten beizutragen. Dein Engagement trägt nicht nur dazu bei, die Qualität unserer Repositorys zu verbessern, sondern kommt auch der gesamten Computer-Vision-Community zugute. Dieser Leitfaden enthält klare Richtlinien und bewährte Vorgehensweisen, die dir den Einstieg erleichtern.

Verhaltenskodex#

Damit eine einladende und inklusive Umgebung für alle gewährleistet ist, müssen sich alle Mitwirkenden an unseren Verhaltenskodex halten. Respekt, Freundlichkeit und Professionalität bilden das Fundament unserer Community.

Beitragen ü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 diese Schritte:

1. Repository forken: Forke zunächst das relevante Ultralytics-Repository (z. B. ultralytics/ultralytics in deinem GitHub-Konto.
2. Branch erstellen: Erstelle in deinem geforkten Repository einen neuen Branch mit einem klaren, aussagekräftigen Namen, der deine Änderungen widerspiegelt (z. B. fix-issue-123, add-feature-xyz).
3. Änderungen vornehmen: Implementiere deine Verbesserungen oder Fehlerbehebungen. 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 zu bestätigen, 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 kurzen und aussagekräftigen Commit-Nachrichten. Wenn sich deine Änderungen auf ein bestimmtes Issue beziehen, füge die Issue-Nummer hinzu (z. B. Fix #123: Corrected calculation error.).
6. Pull Request erstellen: Erstelle von deinem Branch aus einen Pull Request zum Branch main des ursprünglichen Ultralytics-Repositorys. Gib einen klaren Titel und eine ausführliche Beschreibung an, in der Zweck und Umfang deiner Änderungen erläutert werden.

Entwicklungsinstallation#

Klone dein Fork (oder das Hauptrepository) und installiere es im bearbeitbaren Modus (-e), damit Python deine lokalen Dateien ausführt und jede Änderung übernimmt, ohne dass eine Neuinstallation erforderlich ist:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Damit ein anderes Projekt von einem Fork anstelle des PyPI-Pakets abhängt, verweise pip oder requirements.txt auf den Branch des Forks:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Dokumentationsänderungen#

Der Quelltext der Dokumentation befindet sich unter docs/en/. Installiere im Stammverzeichnis des Repositorys die Entwicklungsabhängigkeiten und führe vor dem Öffnen eines PRs die vollständige strikte Validierung aus:

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

Die Validierung erstellt generierte Referenzen, Makros und Vergleichsseiten, bevor sie zensical build --strict ausführt. Für eine schnellere Live-Vorschau von Seiten ohne Makros führe zensical serve aus.

CLA-Unterzeichnung#

Bevor wir deinen Pull Request zusammenführen können, musst du unsere Contributor-Lizenzvereinbarung (CLA) unterzeichnen. Diese rechtliche Vereinbarung stellt sicher, dass deine Beiträge ordnungsgemäß lizenziert sind, sodass das Projekt weiterhin unter der AGPL-3.0-Lizenz verbreitet werden kann.

Nachdem du deinen Pull Request eingereicht hast, führt dich der CLA-Bot durch den Unterzeichnungsprozess. Um die CLA zu unterzeichnen, füge einfach einen Kommentar in deinem PR mit folgendem Inhalt hinzu:

I have read the CLA Document and I sign the CLA

Docstrings im Google-Stil#

Füge beim Hinzufügen neuer Funktionen oder Klassen Docstrings im Google-Stil ein, um eine klare, standardisierte Dokumentation zu gewährleisten. Schließe sowohl die Eingabe als auch die 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

CI-Tests mit GitHub Actions#

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

Best Practices für Code-Beiträge#

Behalte beim Beitragen von Code zu Ultralytics-Projekten die folgenden bewährten Vorgehensweisen im Hinterkopf:

• Code-Duplikation vermeiden: Verwende vorhandenen Code nach Möglichkeit wieder und minimiere unnötige Argumente.
• Kleinere, fokussierte Änderungen vornehmen: Konzentriere dich auf gezielte Anpassungen statt auf groß angelegte Änderungen.
• Wenn möglich vereinfachen: Suche nach Möglichkeiten, den Code zu vereinfachen oder unnötige Bestandteile zu entfernen.
• Kompatibilität berücksichtigen: Überlege vor Änderungen, ob sie bestehenden Code, der Ultralytics verwendet, beeinträchtigen könnten.
• Einheitliche Formatierung verwenden: Tools wie der Ruff Formatter können dabei helfen, einen einheitlichen Stil beizubehalten.
• Geeignete Tests hinzufügen: Füge für neue Funktionen Tests hinzu, um sicherzustellen, dass sie wie erwartet funktionieren.

Überprüfen von Pull Requests#

Die Überprüfung von Pull Requests ist eine weitere wertvolle Möglichkeit, beizutragen. Achte beim Überprüfen von PRs auf Folgendes:

• Auf Unit-Tests prüfen: Stelle sicher, dass der PR Tests für neue Funktionen oder Änderungen enthält.
• Dokumentationsänderungen überprüfen: Stelle sicher, dass die Dokumentation aktualisiert wurde und die Änderungen widerspiegelt.
• Auswirkungen auf die Leistung bewerten: Überlege, wie sich Änderungen auf die Leistung auswirken könnten.
• CI-Tests überprüfen: Bestätige, dass alle Tests der kontinuierlichen Integration erfolgreich sind.
• Konstruktives Feedback geben: Gib spezifisches und klares Feedback zu Problemen oder Bedenken.
• Einsatz anerkennen: Würdige die Arbeit der Autorin oder des Autors, um eine positive, gemeinschaftliche Atmosphäre zu bewahren.

Fehler melden#

Wir schätzen Fehlermeldungen sehr, da sie uns helfen, die Qualität und Zuverlässigkeit unserer Projekte zu verbessern. Beachte beim Melden eines Fehlers über GitHub Issues Folgendes:

• Bestehende Issues prüfen: Suche zuerst, um festzustellen, ob der Fehler bereits gemeldet wurde.
• Ein kleinstes reproduzierbares Beispiel bereitstellen: Erstelle einen kleinen, in sich geschlossenen Codeausschnitt, der das Problem zuverlässig reproduziert. Das ist für eine effiziente Fehlersuche entscheidend.
• Umgebung beschreiben: Gib dein Betriebssystem, deine Python-Version, relevante Bibliotheksversionen (z. B. torch, ultralytics) und deine Hardware (CPU/GPU) an.
• Erwartetes und tatsächliches Verhalten erklären: Beschreibe klar, was deiner Erwartung nach geschehen sollte und was tatsächlich passiert ist. Füge alle Fehlermeldungen oder Tracebacks hinzu.

Lizenz#

Ultralytics verwendet für seine Repositorys die GNU Affero General Public License, Version 3.0 (AGPL-3.0). Diese Lizenz fördert Offenheit, Transparenz und gemeinschaftliche Weiterentwicklung in der Softwareentwicklung. Sie stellt sicher, dass alle Nutzenden die Freiheit haben, die Software zu verwenden, zu ändern und weiterzugeben, und fördert so eine starke Gemeinschaft der Zusammenarbeit und Innovation.

Wir empfehlen allen Mitwirkenden, sich mit den Bedingungen der AGPL-3.0-Lizenz vertraut zu machen, um effektiv und verantwortungsvoll zur Open-Source-Community von Ultralytics beizutragen.

Dein YOLO-Projekt unter AGPL-3.0 als Open Source veröffentlichen#

Verwendest du Ultralytics-YOLO-Modelle oder -Code in deinem Projekt? Die AGPL-3.0-Lizenz verlangt, dass auch dein gesamtes abgeleitetes Werk unter AGPL-3.0 als Open Source veröffentlicht wird. Dadurch bleiben Änderungen und größere Projekte, die auf Open-Source-Grundlagen aufbauen, offen.

Warum die Einhaltung der AGPL-3.0 wichtig ist#

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

Wenn du dein Projekt nicht als Open Source veröffentlichen möchtest, solltest du eine Enterprise-Lizenz erwerben.

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 zugänglich zu machen.

1. Ausgangspunkt auswählen:

   • Ultralytics YOLO forken: Forke direkt das Ultralytics-YOLO-Repository, wenn du eng darauf aufbaust.
   • Ultralytics-Vorlage verwenden: Beginne mit dem Ultralytics-Vorlagenrepository, um eine klare, modulare Einrichtung mit YOLO zu erhalten.

2. Projekt lizenzieren:

   • Füge eine Datei LICENSE hinzu, die den vollständigen Text der AGPL-3.0-Lizenz enthält.
   • Füge am Anfang jeder Quelldatei einen Hinweis auf die Lizenz ein.

3. Quellcode veröffentlichen:

   • Mache den gesamten Quellcode deines Projekts öffentlich zugänglich (z. B. auf GitHub). Dazu gehören:
     • Die vollständige größere Anwendung oder das vollständige größere System, in das das YOLO-Modell oder der YOLO-Code integriert ist.
     • Alle Änderungen am ursprünglichen Ultralytics-YOLO-Code.
     • Skripte für Training, Validierung und Inferenz.
     • Modellgewichte, wenn sie geändert oder feinabgestimmt wurden.
     • Konfigurationsdateien, Umgebungsdefinitionen (requirements.txt, Dockerfiles).
     • Backend- und Frontend-Code, wenn er Bestandteil einer Webanwendung ist.
     • Alle von dir geänderten Bibliotheken von Drittanbietern.
     • Trainingsdaten, wenn sie zum Ausführen oder erneuten Trainieren erforderlich und weiterverteilbar sind.

4. Klar dokumentieren:

   • Aktualisiere deine README.md, um anzugeben, dass das Projekt unter AGPL-3.0 lizenziert ist.
   • Füge klare Anweisungen hinzu, wie dein Projekt aus dem Quellcode eingerichtet, erstellt und ausgeführt wird.
   • Gib Ultralytics YOLO angemessen als Quelle an 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.

Beispielstruktur eines Repositorys#

Eine praktische Beispielstruktur findest du im Ultralytics-Vorlagenrepository:

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 Einhaltung 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, zu Ultralytics-Open-Source-YOLO-Projekten beizutragen. Deine Beteiligung ist entscheidend dafür, die Zukunft unserer Software mitzugestalten und eine lebendige Gemeinschaft der Innovation und Zusammenarbeit aufzubauen. Ob du Code verbesserst, Fehler meldest oder neue Funktionen vorschlägst – deine Beiträge sind von unschätzbarem Wert.

Wir freuen uns darauf, deine Ideen Wirklichkeit werden zu sehen, und schätzen dein Engagement für die Weiterentwicklung der Technologie zur Objekterkennung. Lass uns diese spannende Open-Source-Reise gemeinsam fortsetzen und weiter wachsen und innovativ sein.

FAQ#