Mitwirken an Open-Source-Projekten von Ultralytics
Vielen Dank, dass du einen Beitrag zu unseren Ultralytics-Open-Source-Projekten in Betracht ziehst. 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 enthält klare Richtlinien und bewährte Vorgehensweisen, die dir den Einstieg erleichtern.
Ansehen: So trägst du zum Ultralytics-Repository bei | Ultralytics-Modelle, Datensätze und Dokumentation 🚀
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:
- Erstelle einen Fork des Repositorys: Erstelle zunächst einen Fork des passenden Ultralytics-Repositorys (z. B. ultralytics/ultralytics in deinem GitHub-Konto.
- 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). - 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.
- Teste deine Änderungen: Teste deine Änderungen vor dem Einreichen lokal, um sicherzustellen, dass sie wie erwartet funktionieren und keine Regressionen verursachen. Bestehende Tests decken die meisten Änderungen ab, daher sind neue Tests oft nicht nötig; wenn ein neuer Test hilfreich ist, füge lieber ein paar Zeilen zu einer bestehenden Testdatei hinzu, statt Tests mit Mock-Objekten zu schreiben.
- 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.). - Erstelle einen Pull Request: Reiche aus deinem Branch einen Pull Request an den Branch
maindes 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.pyBei 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 CLADocstrings 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)).
Dieses Beispiel zeigt das Standardformat für Docstrings im Google-Stil. Achte darauf, wie es die Funktionsbeschreibung, Argumente, den Rückgabewert und Beispiele übersichtlich voneinander trennt.
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 == arg2CI-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.
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 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 Repositories die GNU Affero General Public License v3.0 (AGPL-3.0). Diese Lizenz fördert Offenheit, Transparenz und gemeinschaftliche Weiterentwicklung in der Softwareentwicklung. Sie stellt sicher, dass alle Nutzer die Freiheit haben, die Software zu verwenden, zu ändern und weiterzugeben, und stärkt so eine engagierte Gemeinschaft, die gemeinsam Innovationen vorantreibt.
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.
-
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.
-
Dein Projekt lizenzieren:
- Füge eine Datei namens
LICENSEmit dem vollständigen Text der AGPL-3.0-Lizenz hinzu. - Füge am Anfang jeder Quelldatei einen Hinweis auf die Lizenz ein.
- Füge eine Datei namens
-
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.
- Stelle den gesamten Quellcode deines Projekts öffentlich zugänglich bereit (z. B. auf GitHub). Dazu gehören:
-
Alles klar dokumentieren:
- Aktualisiere deine
README.mdund 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.
- Aktualisiere deine
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.ymlWenn 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 den Open-Source-YOLO-Projekten von Ultralytics beizutragen. Deine Beteiligung prägt unsere Software und Community – ganz gleich, ob du den Code verbesserst, Fehler meldest oder neue Funktionen vorschlägst.
Wir schätzen dein Engagement für die Weiterentwicklung der Objekterkennung und freuen uns auf deine Beiträge.
Häufig gestellte Fragen#
Beiträge zu den Open-Source-Repositorys von Ultralytics YOLO verbessern die Software und machen sie für die gesamte Community robuster und funktionsreicher. Dazu gehören beispielsweise Verbesserungen am Code, Fehlerbehebungen, Ergänzungen der Dokumentation und die Implementierung neuer Funktionen. Außerdem kannst du mit anderen erfahrenen Entwicklerinnen und Entwicklern sowie Fachleuten auf diesem Gebiet zusammenarbeiten und so deine eigenen Fähigkeiten und deinen Ruf stärken. Wie du loslegen kannst, erfährst du im Abschnitt Mitwirkung über Pull Requests.
Um die Contributor License Agreement (CLA) zu unterzeichnen, folge den Anweisungen des CLA-Bots, nachdem du deinen Pull Request eingereicht hast. So wird sichergestellt, dass deine Beiträge ordnungsgemäß unter der AGPL-3.0-Lizenz lizenziert werden und die rechtliche Integrität des Open-Source-Projekts gewahrt bleibt. Füge in deinem Pull Request folgenden Kommentar hinzu:
I have read the CLA Document and I sign the CLAWeitere Informationen findest du im Abschnitt CLA-Unterzeichnung.
Docstrings im Google-Stil dokumentieren Funktionen und Klassen klar und knapp und verbessern so die Lesbarkeit und Wartbarkeit des Codes. Sie beschreiben Zweck, Argumente und Rückgabewerte einer Funktion anhand konkreter Formatierungsregeln. Wenn du zu Ultralytics YOLO beiträgst, sorgen Docstrings im Google-Stil dafür, dass deine Ergänzungen gut dokumentiert und leicht verständlich sind. Beispiele und Richtlinien findest du im Abschnitt Docstrings im Google-Stil.
Bevor dein Pull Request zusammengeführt werden kann, muss er alle GitHub-Actions-Tests zur kontinuierlichen Integration (CI) bestehen. Dazu gehören Linting, Unit-Tests und weitere Prüfungen, mit denen sichergestellt wird, dass der Code den Qualitätsstandards des Projekts entspricht. Prüfe die CI-Ausgabe und behebe alle Probleme. Ausführliche Informationen zum CI-Prozess und Tipps zur Fehlerbehebung findest du im Abschnitt GitHub-Actions-CI-Tests.
Um einen Fehler zu melden, füge deiner Fehlermeldung ein klares und knappes minimales reproduzierbares Beispiel hinzu. So können Entwicklerinnen und Entwickler das Problem schnell erkennen und beheben. Achte darauf, dass dein Beispiel so klein wie möglich ist und das Problem dennoch reproduziert. Ausführlichere Schritte zum Melden von Fehlern findest du im Abschnitt Fehler melden.
Wenn du Code oder Modelle von Ultralytics YOLO (lizenziert unter AGPL-3.0) in deinem Projekt verwendest, verlangt die AGPL-3.0-Lizenz, dass auch dein gesamtes Projekt (das abgeleitete Werk) unter AGPL-3.0 lizenziert und sein vollständiger Quellcode öffentlich zugänglich gemacht wird. Dadurch bleibt der Open-Source-Charakter der Software auch in allen daraus abgeleiteten Werken erhalten. Wenn du diese Anforderungen nicht erfüllen kannst, musst du eine Enterprise-Lizenz erwerben. Einzelheiten findest du im Abschnitt Dein Projekt als Open Source veröffentlichen.
Kommentare7
Stell eine Frage, teile deine Ergebnisse oder hilf jemand anderem.
Mehrab-Shahbazi
Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).
Mehrab-Shahbazi
by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)
Glenn JocherUltralytics@Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.
Mehrab-Shahbazi
thank for your reply
esssyjr
Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.
Glenn JocherUltralytics@esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including
train/andval/folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.esssyjr
Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU
