Beiträge zu Ultralytics Open-Source-Projekten

Willkommen! Wir freuen uns, dass Sie in Erwägung ziehen, zu unseren Ultralytics Open-Source-Projekten beizutragen. Ihre Beteiligung trägt nicht nur zur Verbesserung der Qualität unserer Repositories bei, sondern kommt auch der gesamten Computer Vision-Community zugute. Dieser Leitfaden bietet klare Richtlinien und Best Practices, die Ihnen den Einstieg erleichtern.

Ansehen: Wie man zum Ultralytics Repository beiträgt | Ultralytics Modelle, Datasets und Dokumentation 🚀

🤝 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 schätzen Beiträge in Form von Pull Requests (PRs) sehr. Um den Review-Prozess so reibungslos wie möglich zu gestalten, befolgen Sie bitte diese Schritte:

1. Repository forken: Beginnen Sie mit dem Forken des entsprechenden Ultralytics-Repositorys (z. B. ultralytics/ultralytics) in Ihr GitHub-Konto.
2. Einen Branch erstellen: Erstellen Sie einen neuen Branch in Ihrem geforkten Repository mit einem klaren, beschreibenden Namen, der Ihre Änderungen widerspiegelt (z. B. fix-issue-123, add-feature-xyz), oder Auto-Modus mit angegebener Auslastungsfraktion (
3. Nehmen Sie Ihre Änderungen vor: Implementieren Sie Ihre Verbesserungen oder Fehlerbehebungen. Stellen Sie sicher, dass Ihr Code den Stilrichtlinien des Projekts entspricht und keine neuen Fehler oder Warnungen einführt.
4. Testen Sie Ihre Änderungen: Testen Sie Ihre Änderungen vor dem Einreichen lokal, um zu bestätigen, dass sie wie erwartet funktionieren und keine Regressionen verursachen. Fügen Sie Tests hinzu, wenn Sie neue Funktionen einführen.
5. Änderungen committen: Übernehmen Sie Ihre Änderungen mit prägnanten und aussagekräftigen Commit-Nachrichten. Wenn Ihre Änderungen ein bestimmtes Problem betreffen, geben Sie die Problemnummer an (z. B. Fix #123: Corrected calculation error.), oder Auto-Modus mit angegebener Auslastungsfraktion (
6. Einen Pull Request erstellen: Senden Sie einen Pull-Request von Ihrem Branch an den main Zweig des ursprünglichen Ultralytics-Repositorys. Geben Sie einen klaren Titel und eine detaillierte Beschreibung an, die den Zweck und den Umfang Ihrer Änderungen erläutert.

📝 CLA-Unterzeichnung

Bevor wir Ihren Pull-Request zusammenführen können, müssen Sie unsere Contributor License Agreement (CLA) unterzeichnen. Diese rechtliche Vereinbarung stellt sicher, dass Ihre Beiträge ordnungsgemäß lizenziert sind, sodass das Projekt weiterhin unter der AGPL-3.0-Lizenz vertrieben werden kann.

Nach dem Einreichen Ihres Pull Requests führt Sie der CLA-Bot durch den Signierungsprozess. Um die CLA zu unterzeichnen, fügen Sie einfach einen Kommentar in Ihrem PR hinzu, der Folgendes besagt:

I have read the CLA Document and I sign the CLA

✍️ Google-Style Docstrings

Beim Hinzufügen neuer Funktionen oder Klassen, einschließen Google-Style Docstrings für eine klare, standardisierte Dokumentation. Immer sowohl Eingabe als auch Ausgabe einschließen types in Klammern (z. B. (bool), (np.ndarray)), oder Auto-Modus mit angegebener Auslastungsfraktion (

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

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

def example_function(arg1: int, arg2: int = 4) -> bool:
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ GitHub Actions CI Tests

Alle Pull-Requests müssen die GitHub Actions Continuous Integration (CI)-Tests bestehen, bevor sie zusammengeführt werden können. Diese Tests umfassen Linting, Unit-Tests und andere Prüfungen, um sicherzustellen, dass Ihre Änderungen die Qualitätsstandards des Projekts erfüllen. Überprüfen Sie die CI-Ausgabe und beheben Sie alle auftretenden Probleme.

✨ Best Practices für Code-Beiträge

Wenn Sie Code zu Ultralytics-Projekten beitragen, beachten Sie diese Best Practices:

• Doppelte Code vermeiden: Verwenden Sie nach Möglichkeit vorhandenen Code wieder und minimieren Sie unnötige Argumente.
• Kleinere, fokussierte Änderungen vornehmen: Konzentrieren Sie sich auf gezielte Modifikationen anstatt auf groß angelegte Änderungen.
• Wenn möglich, vereinfachen: Suchen Sie nach Möglichkeiten, den Code zu vereinfachen oder unnötige Teile zu entfernen.
• Kompatibilität beachten: Bevor Sie Änderungen vornehmen, sollten Sie prüfen, ob diese vorhandenen Code, der Ultralytics verwendet, beeinträchtigen könnten.
• Konsistente Formatierung verwenden: Tools wie Ruff Formatter können helfen, die stilistische Konsistenz zu wahren.
• Füge geeignete Tests hinzu: Füge Tests für neue Funktionen hinzu, um sicherzustellen, dass sie wie erwartet funktionieren.

👀 Pull-Requests überprüfen

Das Überprüfen von Pull-Requests ist eine weitere wertvolle Möglichkeit, einen Beitrag zu leisten. Bei der Überprüfung von PRs:

• Auf Unit-Tests prüfen: Stellen Sie sicher, dass der PR Tests für neue Funktionen oder Änderungen enthält.
• Dokumentationsaktualisierungen überprüfen: Stellen Sie sicher, dass die Dokumentation aktualisiert wird, um Änderungen widerzuspiegeln.
• Auswirkungen auf die Leistung bewerten: Berücksichtigen Sie, wie sich Änderungen auf die Leistung auswirken könnten.
• CI-Tests verifizieren: Bestätigen Sie, dass alle Continuous Integration Tests bestanden wurden.
• Geben Sie konstruktives Feedback: Geben Sie spezifisches, klares Feedback zu Problemen oder Bedenken.
• Bemühungen anerkennen: Die Arbeit des Autors anerkennen, um eine positive, kollaborative Atmosphäre zu erhalten.

🐞 Fehler melden

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

• Vorhandene Probleme prüfen: Suchen Sie zuerst, um festzustellen, ob der Fehler bereits gemeldet wurde.
• Stellen Sie ein minimal reproduzierbares Beispiel bereit: Erstellen Sie einen kleinen, in sich geschlossenen Code-Abschnitt, der das Problem konsistent reproduziert. Dies ist entscheidend für eine effiziente Fehlersuche.
• Beschreiben Sie die Umgebung: Geben Sie Ihr Betriebssystem, Ihre Python-Version und relevante Bibliotheksversionen an (z. B. torch, ultralytics), und Hardware (CPU/GPU), oder Auto-Modus mit angegebener Auslastungsfraktion (
• Erläutern Sie das erwartete vs. tatsächliche Verhalten: Geben Sie klar an, was Sie erwartet haben und was tatsächlich geschehen ist. Fügen Sie alle Fehlermeldungen oder Tracebacks hinzu.

📜 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 gemeinschaftliche Verbesserung in der Softwareentwicklung. Sie stellt sicher, dass alle Benutzer die Freiheit haben, die Software zu nutzen, zu verändern und zu teilen, wodurch eine starke Gemeinschaft der Zusammenarbeit und Innovation gefördert wird.

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-Sourcing Ihres YOLO-Projekts unter AGPL-3.0

Verwenden Sie Ultralytics YOLO-Modelle oder -Code in Ihrem Projekt? Die AGPL-3.0-Lizenz schreibt vor, dass Ihr gesamtes abgeleitetes Werk ebenfalls unter AGPL-3.0 Open-Source sein muss. 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 unter AGPL-3.0 lizenzierter Software bindet Ihr Projekt an deren Bedingungen.
• Fördert die Zusammenarbeit: Fördert Austausch und Transparenz.

Wenn Sie es vorziehen, Ihr Projekt nicht als Open-Source zu veröffentlichen, sollten Sie eine Enterprise-Lizenz erwerben.

Wie man die AGPL-3.0 einhält

Die Einhaltung bedeutet, dass der vollständige zugehörige Quellcode Ihres Projekts unter der AGPL-3.0-Lizenz öffentlich zugänglich gemacht wird.

1. Wählen Sie Ihren Ausgangspunkt:

   • Ultralytics YOLO forken: Forken Sie direkt das Ultralytics YOLO Repository, wenn Sie eng darauf aufbauen.
   • Ultralytics-Vorlage verwenden: Beginnen Sie mit dem Ultralytics-Vorlagen-Repository für ein sauberes, modulares Setup, das YOLO integriert.

2. Lizenzieren Sie Ihr Projekt:

   • Fügen Sie einen LICENSE Datei, die den vollständigen Text der AGPL-3.0-Lizenz.
   • Fügen Sie am Anfang jeder Quelldatei einen Hinweis hinzu, der die Lizenz angibt.

3. Veröffentlichen Sie Ihren Quellcode:

   • Gestalten Sie Ihre gesamten Quellcode des 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 Änderungen, die am ursprünglichen Ultralytics YOLO-Code vorgenommen wurden.
     • Skripte für Training, Validierung, Inferenz.
     • Modellgewichte, falls geändert oder feinabgestimmt.
     • Konfigurationsdateien, Umgebungseinrichtungen (requirements.txt, Dockerfiles), oder Auto-Modus mit angegebener Auslastungsfraktion (
     • Backend- und Frontend-Code, wenn er Teil einer Webanwendung ist.
     • Alle Drittanbieterbibliotheken, die Sie geändert haben.
     • Trainingsdaten, falls erforderlich, um sie auszuführen/neu zu trainieren und weiterzuverteilen.

4. Klar Dokumentieren:

   • Aktualisiere deine README.md anzugeben, dass das Projekt unter AGPL-3.0 lizenziert ist.
   • Fügen Sie klare Anweisungen zum Einrichten, Erstellen und Ausführen Ihres Projekts aus dem Quellcode hinzu.
   • Nennen Sie Ultralytics YOLO in angemessener Weise und verlinken Sie zurück zu ursprüngliches 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 finden Sie im Ultralytics Template Repository:

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 Sie diese Richtlinien befolgen, stellen Sie die Einhaltung von AGPL-3.0 sicher und unterstützen das Open-Source-Ökosystem, das leistungsstarke Tools wie Ultralytics YOLO ermöglicht.

🎉 Fazit

Vielen Dank für Ihr Interesse an der Mitwirkung an Ultralytics Open-Source YOLO-Projekten. Ihre Teilnahme ist entscheidend für die Gestaltung der Zukunft unserer Software und den Aufbau einer lebendigen Community für Innovation und Zusammenarbeit. Ob Sie Code verbessern, Fehler melden oder neue Funktionen vorschlagen, Ihre Beiträge sind von unschätzbarem Wert.

Wir freuen uns darauf, Ihre Ideen zum Leben zu erwecken, und schätzen Ihr Engagement für die Weiterentwicklung der Objekterkennungstechnologie. Lassen Sie uns gemeinsam auf dieser spannenden Open-Source-Reise weiter wachsen und Innovationen entwickeln. Viel Spaß beim Programmieren! 🚀🌟

FAQ

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

Beiträge zu Ultralytics YOLO Open-Source-Repositories verbessern die Software und machen sie robuster und funktionsreicher für die gesamte Community. Beiträge können Code-Erweiterungen, Fehlerbehebungen, Verbesserungen der Dokumentation und die Implementierung neuer Funktionen umfassen. Darüber hinaus ermöglicht die Mitwirkung die Zusammenarbeit mit anderen qualifizierten Entwicklern und Experten auf diesem Gebiet, wodurch Ihre eigenen Fähigkeiten und Ihr Ruf verbessert werden. Einzelheiten zum Einstieg finden Sie im Abschnitt Beitragen über Pull-Requests.

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

Um die Contributor License Agreement (CLA) zu unterzeichnen, befolgen Sie die Anweisungen des CLA-Bots, nachdem Sie Ihren Pull-Request eingereicht haben. Dieser Prozess stellt sicher, dass Ihre Beiträge ordnungsgemäß unter der AGPL-3.0-Lizenz lizenziert sind, wodurch die rechtliche Integrität des Open-Source-Projekts gewahrt bleibt. Fügen Sie in Ihrem Pull-Request einen Kommentar hinzu, der Folgendes besagt:

I have read the CLA Document and I sign the CLA

Weitere Informationen finden Sie im Abschnitt CLA-Unterzeichnung.

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

Google-Style Docstrings bieten eine klare, prägnante Dokumentation für Funktionen und Klassen, wodurch die Lesbarkeit und Wartbarkeit des Codes verbessert wird. Diese Docstrings beschreiben den Zweck, die Argumente und die Rückgabewerte der Funktion mit spezifischen Formatierungsregeln. Wenn Sie zu Ultralytics YOLO beitragen, stellen Sie durch die Verwendung von Google-Style Docstrings sicher, dass Ihre Ergänzungen gut dokumentiert und leicht verständlich sind. Beispiele und Richtlinien finden Sie im Abschnitt Google-Style Docstrings.

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

Bevor Ihr Pull-Request zusammengeführt werden kann, muss er alle GitHub Actions Continuous Integration (CI)-Tests bestehen. Diese Tests umfassen Linting, Unit-Tests und andere Prüfungen, um sicherzustellen, dass der Code die Qualitätsstandards des Projekts erfüllt. Überprüfen Sie die CI-Ausgabe und beheben Sie alle Probleme. Detaillierte Informationen zum CI-Prozess und Tipps zur Fehlerbehebung finden Sie im Abschnitt GitHub Actions CI Tests.

Wie melde ich einen Fehler in Ultralytics YOLO Repositories?

Um einen Fehler zu melden, geben Sie ein klares und prägnantes Minimal Reproducible Example zusammen mit Ihrem Fehlerbericht an. Dies hilft Entwicklern, das Problem schnell zu identifizieren und zu beheben. Stellen Sie sicher, dass Ihr Beispiel minimal, aber ausreichend ist, um das Problem zu reproduzieren. Detailliertere Schritte zum Melden von Fehlern finden Sie im Abschnitt Fehler melden.

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

Wenn Sie Ultralytics YOLO-Code oder -Modelle (lizenziert unter AGPL-3.0) in Ihrem Projekt verwenden, erfordert die AGPL-3.0-Lizenz, dass Ihr gesamtes Projekt (das abgeleitete Werk) ebenfalls unter AGPL-3.0 lizenziert und sein vollständiger Quellcode öffentlich zugänglich gemacht werden muss. Dies stellt sicher, dass der Open-Source-Charakter der Software während ihrer Derivate erhalten bleibt. Wenn Sie diese Anforderungen nicht erfüllen können, müssen Sie eine Enterprise-Lizenz erwerben. Weitere Informationen finden Sie im Abschnitt Open-Sourcing Ihres Projekts.

📅 Vor 1 Jahr erstellt ✏️ Vor 1 Monat aktualisiert

Kommentare