Mitwirken an Open-Source-Projekten von Ultralytics#

Willkommen! Wir freuen uns sehr, dass du einen Beitrag zu unseren Ultralytics-Open-Source-Projekten leisten möchtest. Dein Engagement trägt nicht nur dazu bei, die Qualität unserer Repositorys zu verbessern, sondern kommt auch der gesamten Bildverarbeitungs-Community zugute. Dieser Leitfaden enthält klare Richtlinien und bewährte Vorgehensweisen für deinen Einstieg.

Verhaltenskodex#

Damit sich alle willkommen und einbezogen fühlen, müssen sich alle Mitwirkenden an unseren Verhaltenskodex halten. Respekt, Freundlichkeit und Professionalität prägen unsere Community.

Mitwirken über Pull Requests#

Beiträge in Form von Pull Requests (PRs) sind sehr willkommen. Damit der Review-Prozess möglichst reibungslos abläuft, befolge bitte diese Schritte:

1. Erstelle einen Fork des Repositorys: Erstelle zunächst einen Fork des passenden Ultralytics-Repositorys (z. B. ultralytics/ultralytics in deinem GitHub-Konto.
2. Erstelle einen Branch: Erstelle in deinem Fork einen neuen Branch mit einem klaren, aussagekräftigen Namen, der deine Änderungen beschreibt (z. B. fix-issue-123, add-feature-xyz).
3. Nimm deine Änderungen vor: Setze deine Verbesserungen oder Fehlerbehebungen um. Achte darauf, dass dein Code den Stilrichtlinien des Projekts entspricht und keine neuen Fehler oder Warnungen verursacht.
4. Teste deine Änderungen: Teste deine Änderungen vor dem Einreichen lokal, um sicherzustellen, dass sie wie erwartet funktionieren und keine Regressionen verursachen. Ergänze Tests, wenn du neue Funktionen einführst.
5. Committe deine Änderungen: Verwende kurze, aussagekräftige Commit-Nachrichten. Wenn deine Änderungen ein bestimmtes Problem beheben, nenne die Nummer des Issues (z. B. Fix #123: Corrected calculation error.).
6. Erstelle einen Pull Request: Reiche aus deinem Branch einen Pull Request an den Branch main des ursprünglichen Ultralytics-Repositorys ein. Formuliere einen klaren Titel und beschreibe ausführlich Zweck und Umfang deiner Änderungen.

Installation für die Entwicklung#

Klone deinen Fork (oder das Haupt-Repository) und installiere ihn im bearbeitbaren Modus (-e), damit Python deine lokalen Dateien verwendet und alle Änderungen ohne erneute Installation übernimmt:

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

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

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

Änderungen an der Dokumentation#

Der Quellcode der Dokumentation befindet sich unter docs/en/. Installiere im Stammverzeichnis des Repositorys die Entwicklungsabhängigkeiten und führe vor dem Eröffnen eines PR die vollständige strenge Prüfung aus:

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

Bei der Prüfung werden zunächst automatisch generierte Referenzen, Makros und Vergleichsseiten erstellt und anschließend zensical build --strict ausgeführt. Für eine schnellere Live-Vorschau von Seiten ohne Makros führe zensical serve aus.

CLA unterzeichnen#

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

Nach dem Einreichen deines Pull Requests führt dich der CLA-Bot durch den Unterzeichnungsprozess. Um die CLA zu unterzeichnen, füge einfach folgenden Kommentar zu deinem PR 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, damit die Dokumentation klar und einheitlich ist. Setze sowohl Eingabe- als auch Ausgabe-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

CI-Tests mit GitHub Actions#

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

Bewährte Vorgehensweisen für Code-Beiträge#

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

• Vermeide Code-Duplikate: Verwende vorhandenen Code nach Möglichkeit wieder und beschränke unnötige Argumente auf ein Minimum.
• Halte Änderungen klein und gezielt: Konzentriere dich auf gezielte Anpassungen statt auf umfangreiche Änderungen.
• Vereinfache, wo es möglich ist: Suche nach Möglichkeiten, den Code zu vereinfachen oder unnötige Bestandteile zu entfernen.
• Achte auf Kompatibilität: Überlege vor Änderungen, ob sie bestehenden Code beeinträchtigen könnten, der Ultralytics verwendet.
• Sorge für eine einheitliche Formatierung: Tools wie Ruff Formatter helfen dir dabei, den Stil einheitlich zu halten.
• Ergänze passende Tests: Füge für neue Funktionen Tests hinzu, um sicherzustellen, dass sie wie erwartet funktionieren.

Pull Requests überprüfen#

Auch die Überprüfung von Pull Requests ist eine wertvolle Möglichkeit, mitzuwirken. Achte beim Review von PRs auf Folgendes:

• Prüfe die Unit-Tests: Stelle sicher, dass der PR Tests für neue Funktionen oder Änderungen enthält.
• Prüfe Aktualisierungen der Dokumentation: Stelle sicher, dass die Dokumentation die Änderungen widerspiegelt.
• Bewerte die Auswirkungen auf die Leistung: Überlege, wie sich Änderungen auf die Leistung auswirken könnten.
• Prüfe die CI-Tests: Vergewissere dich, dass alle Tests zur kontinuierlichen Integration erfolgreich sind.
• Konstruktives Feedback geben: Gib konkretes, klares Feedback zu Problemen oder Bedenken.
• Einsatz anerkennen: Würdige die Arbeit der Autorin oder des Autors, um eine positive, von Zusammenarbeit geprägte Atmosphäre zu fördern.

Fehler melden#

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

• Vorhandene Issues prüfen: Suche zuerst danach, ob der Fehler bereits gemeldet wurde.
• Ein minimales reproduzierbares Beispiel bereitstellen: Erstelle einen kleinen, eigenständigen Codeausschnitt, mit dem sich das Problem zuverlässig reproduzieren lässt. Das ist entscheidend für eine effiziente Fehlersuche.
• Die Umgebung beschreiben: Gib dein Betriebssystem, deine Python-Version, relevante Bibliotheksversionen (z. B. torch, ultralytics) und die Hardware (CPU/GPU) an.
• Erwartetes und tatsächliches Verhalten erklären: Beschreibe klar, was deiner Erwartung nach passieren 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 gemeinsame Weiterentwicklung in der Softwareentwicklung. Sie stellt sicher, dass alle Nutzerinnen und Nutzer die Freiheit haben, die Software zu verwenden, zu ändern und weiterzugeben, und stärkt so eine von Zusammenarbeit und Innovation geprägte Community.

Wir empfehlen allen Mitwirkenden, sich mit den Bedingungen der AGPL-3.0-Lizenz vertraut zu machen, damit sie wirksam und verantwortungsvoll zur Open-Source-Community von Ultralytics beitragen können.

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. So bleiben Änderungen und größere Projekte, die auf Open-Source-Grundlagen aufbauen, ebenfalls offen.

Warum die Einhaltung der AGPL-3.0 wichtig ist#

• Hält Software offen: Stellt sicher, dass Verbesserungen und abgeleitete Werke der Community zugutekommen.
• Gesetzliche Verpflichtung: Wenn du Code verwendest, der unter AGPL-3.0 lizenziert ist, muss sich dein Projekt an deren Bedingungen halten.
• 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, dass der vollständige zugehörige Quellcode deines Projekts unter der AGPL-3.0-Lizenz öffentlich zugänglich gemacht wird.

1. Ausgangspunkt wählen:

   • Ultralytics YOLO forken: Forke direkt das Ultralytics-YOLO-Repository, wenn du eng darauf aufbauen möchtest.
   • Ultralytics-Vorlage verwenden: Beginne mit dem Ultralytics-Vorlagenrepository, um eine übersichtliche, modulare Struktur mit integrierter YOLO-Unterstützung zu erhalten.

2. Dein Projekt lizenzieren:

   • Füge eine Datei namens LICENSE mit dem vollständigen Text der AGPL-3.0-Lizenz hinzu.
   • Füge am Anfang jeder Quelldatei einen Hinweis auf die Lizenz ein.

3. Deinen Quellcode veröffentlichen:

   • Stelle den gesamten Quellcode deines Projekts öffentlich zugänglich bereit (z. B. auf GitHub). Dazu gehören:
     • Die vollständige übergeordnete Anwendung oder das System, in das das YOLO-Modell oder der YOLO-Code eingebunden ist.
     • Alle Änderungen am ursprünglichen Ultralytics-YOLO-Code.
     • Skripte für Training, Validierung und Inferenz.
     • Modellgewichte, falls sie geändert oder feinabgestimmt wurden.
     • Konfigurationsdateien, Umgebungsdefinitionen (requirements.txt, Dockerfiles).
     • Backend- und Frontend-Code, falls er Teil einer Webanwendung ist.
     • Alle Bibliotheken von Drittanbietern, die du geändert hast.
     • Trainingsdaten, falls sie zum Ausführen oder erneuten Trainieren benötigt werden und weitergegeben werden dürfen.

4. Alles klar dokumentieren:

   • Aktualisiere deine README.md und gib darin an, dass das Projekt unter AGPL-3.0 lizenziert ist.
   • Füge klare Anweisungen hinzu, wie sich dein Projekt aus dem Quellcode einrichten, erstellen und ausführen lässt.
   • Nenne Ultralytics YOLO korrekt 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 für eine Repository-Struktur#

Ein praktisches Beispiel für eine solche Struktur 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

Wenn du diese Richtlinien befolgst, hältst du die AGPL-3.0 ein 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 Mitwirkung ist entscheidend, um die Zukunft unserer Software zu gestalten und eine lebendige Community aufzubauen, die von Innovation und Zusammenarbeit geprägt ist. Ob du Code verbesserst, Fehler meldest oder neue Funktionen vorschlägst – deine Beiträge sind wertvoll.

Wir freuen uns darauf, deine Ideen Wirklichkeit werden zu sehen, und schätzen deinen Einsatz für die Weiterentwicklung der Technologie zur Objekterkennung. Lass uns gemeinsam auf diesem spannenden Open-Source-Weg weiter wachsen und Neues schaffen.

Häufig gestellte Fragen#