Mitwirkung an Ultralytics Open-Source-Projekten

Herzlich willkommen! Wir freuen uns sehr, dass Sie einen Beitrag zu unserer 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 enthält klare Richtlinien und bewährte Verfahren, um Ihnen den Einstieg zu erleichtern.

Beobachten: Wie man zum Ultralytics Repository beiträgt | Ultralytics Modelle, Datensätze und Dokumentation 🚀

🤝 Verhaltenskodex

Um ein einladendes und integratives Umfeld für alle zu schaffen, müssen sich alle Mitwirkenden an unseren Verhaltenskodex halten. Respekt, Freundlichkeit und Professionalität sind das Herzstück unserer Gemeinschaft.

🚀 Beitragen über Pull Requests

Wir freuen uns sehr über Beiträge in Form von Pull Requests (PRs). Um den Überprüfungsprozess so reibungslos wie möglich zu gestalten, folgen Sie bitte diesen Schritten:

1. Forken Sie das Repository: Beginnen Sie damit, das entsprechende Ultralytics (z. B. ultralytics) in Ihr GitHub-Konto zu forken.
2. Erstellen Sie eine Verzweigung: Erstellen Sie einen neuen Zweig in Ihrem geforkten Repository mit einem klaren, beschreibenden Namen, der Ihre Änderungen widerspiegelt (z.B., fix-issue-123, add-feature-xyz).
3. Nehmen Sie Ihre Änderungen vor: Implementieren Sie Ihre Verbesserungen oder Korrekturen. Stellen Sie sicher, dass Ihr Code die Stilrichtlinien des Projekts einhält und keine neuen Fehler oder Warnungen einführt.
4. Testen Sie Ihre Änderungen: Testen Sie Ihre Änderungen vor dem Absenden lokal, um sicherzustellen, dass sie wie erwartet funktionieren und keine Regressionen verursachen. Fügen Sie Tests hinzu, wenn Sie neue Funktionen einführen.
5. Bestätigen Sie Ihre Änderungen: Übertragen Sie Ihre Änderungen mit kurzen und aussagekräftigen Commit-Nachrichten. Wenn sich Ihre Änderungen auf ein bestimmtes Problem beziehen, geben Sie die Problemnummer an (z. B., Fix #123: Corrected calculation error.).
6. Erstellen Sie eine Pull-Anfrage: Reichen Sie einen Pull-Request von Ihrem Zweig an die main Zweig des ursprünglichen Ultralytics . Geben Sie einen eindeutigen Titel und eine detaillierte Beschreibung an, die den Zweck und den Umfang Ihrer Änderungen erläutert.

📝 GAV-Unterzeichnung

Bevor wir Ihre Anfrage zusammenführen können, müssen Sie unser Contributor License Agreement (CLA) unterschreiben. Diese rechtliche Vereinbarung stellt sicher, dass Ihre Beiträge ordnungsgemäß lizenziert sind, so dass das Projekt weiterhin unter der AGPL-3.0 -Lizenz verbreitet werden kann.

Nachdem Sie Ihre Anfrage eingereicht haben, wird der CLA-Bot Sie durch den Signierungsprozess leiten. Um die GAV zu unterzeichnen, fügen Sie einfach einen Kommentar in Ihren PR ein, in dem Sie angeben:

I have read the CLA Document and I sign the CLA

✍️ Google Docstrings

Wenn Sie neue Funktionen oder Klassen hinzufügen, fügen Sie Doku-Strings Google für eine klare, standardisierte Dokumentation. Fügen Sie immer sowohl Eingabe als auch Ausgabe ein types 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

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-Aktionen CI-Tests

Alle Pull-Anfragen 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 den Qualitätsstandards des Projekts entsprechen. Überprüfen Sie die CI-Ausgabe und beheben Sie alle auftretenden Probleme.

✨ Bewährte Praktiken für Codebeiträge

Wenn Sie Code zu Ultralytics beisteuern, sollten Sie diese bewährten Verfahren beachten:

• Vermeiden Sie doppelten Code: Verwenden Sie vorhandenen Code wieder, wo immer dies möglich ist, und minimieren Sie unnötige Argumente.
• Nehmen Sie kleinere, gezielte Änderungen vor: Konzentrieren Sie sich auf gezielte Änderungen und nicht auf groß angelegte Veränderungen.
• Vereinfachen Sie, wenn möglich: Suchen Sie nach Möglichkeiten, den Code zu vereinfachen oder unnötige Teile zu entfernen.
• Beachten Sie die Kompatibilität: Bevor Sie Änderungen vornehmen, sollten Sie überlegen, ob diese den vorhandenen Code, der Ultralytics verwendet, beeinträchtigen könnten.
• Verwenden Sie eine einheitliche Formatierung: Tools wie Ruff Formatter können helfen, stilistische Konsistenz zu wahren.
• Fügen Sie geeignete Tests hinzu: Fügen Sie Tests für neue Funktionen ein, um sicherzustellen, dass sie wie erwartet funktionieren.

👀 Überprüfung von Pull Requests

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

• Prüfen Sie auf Unit-Tests: Überprüfen Sie, ob der PR Tests für neue Funktionen oder Änderungen enthält.
• Überprüfen Sie die Aktualisierungen der Dokumentation: Stellen Sie sicher, dass die Dokumentation aktualisiert wird, um Änderungen zu berücksichtigen.
• Bewerten Sie die Auswirkungen auf die Leistung: Überlegen Sie, wie sich Änderungen auf die Leistung auswirken könnten.
• Überprüfen Sie die CI-Tests: Bestätigen Sie, dass alle Tests der kontinuierlichen Integration erfolgreich sind.
• Geben Sie konstruktives Feedback: Bieten Sie spezifisches, klares Feedback zu allen Problemen oder Bedenken.
• Erkennen Sie Bemühungen an: Erkennen Sie die Arbeit des Autors an, um eine positive Atmosphäre der Zusammenarbeit zu schaffen.

🐞 Meldung von Fehlern

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:

• Überprüfen Sie bestehende Probleme: Suchen Sie zuerst, um zu sehen, ob der Fehler bereits gemeldet wurde.
• Liefern Sie ein minimal reproduzierbares Beispiel: Erstellen Sie einen kleinen, in sich geschlossenen Codeschnipsel, der das Problem konsistent reproduziert. Dies ist entscheidend für eine effiziente Fehlersuche.
• Beschreiben Sie die Umgebung: Geben Sie Ihr Betriebssystem, die Python , relevante Bibliotheksversionen (z.B., torch, ultralytics), und Hardware (CPU/GPU).
• Erklären Sie das erwartete und das tatsächliche Verhalten: Geben Sie klar und deutlich an, was Sie erwartet haben und was tatsächlich eingetreten ist. Fügen Sie alle Fehlermeldungen oder Rückverfolgungen 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 Verbesserungen in der Softwareentwicklung. Sie gewährleistet, dass alle Benutzer die Freiheit haben, die Software zu verwenden, zu ändern und weiterzugeben, und fördert so eine starke Gemeinschaft der Zusammenarbeit und Innovation.

Wir ermutigen alle Mitwirkenden, sich mit den Bedingungen der AGPL-3.0 vertraut zu machen, um einen effektiven und ethisch vertretbaren Beitrag zur Ultralytics Open-Source-Gemeinschaft zu leisten.

🌍 Open-Sourcing Ihres YOLO unter AGPL-3.0

Verwenden Sie Ultralytics YOLO oder -Code in Ihrem Projekt? Die AGPL-3.0 verlangt, dass Ihre gesamte abgeleitete Arbeit ebenfalls unter der AGPL-3.0 als Open Source angeboten wird. Dadurch wird sichergestellt, dass Änderungen und größere Projekte, die auf Open-Source-Grundlagen aufbauen, offen bleiben.

Warum die Einhaltung der AGPL-3.0 wichtig ist

• Hält die Software offen: Es wird sichergestellt, dass Verbesserungen und abgeleitete Werke der Gemeinschaft zugute kommen.
• Rechtliche Bedingung: Die Verwendung von AGPL-3.0 -lizenziertem Code bindet Ihr Projekt an dessen Bedingungen.
• Fördert die Zusammenarbeit: Ermutigt zu Austausch und Transparenz.

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

Wie man die AGPL-3.0 einhält

Die Einhaltung bedeutet, dass Sie den vollständigen Quellcode Ihres Projekts unter der AGPL-3.0 öffentlich zugänglich machen.

1. Wählen Sie Ihren Startpunkt:

   • Fork Ultralytics YOLO: Forken Sie direkt das Ultralytics YOLO , wenn Sie eng darauf aufbauen.
   • Ultralytics verwenden: Beginnen Sie mit dem Ultralytics für eine saubere, modulare Einrichtung, die YOLO integriert.

2. Lizenzieren Sie Ihr Projekt:

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

3. Veröffentlichen Sie Ihren Quellcode:

   • Machen Sie Ihr den gesamten Quellcode des Projekts öffentlich zugänglich (z. B. auf GitHub). Dies schließt ein:
     • Die komplette größere Anwendung oder das System, das das YOLO oder den Code enthält.
     • Alle am ursprünglichen Ultralytics YOLO vorgenommenen Änderungen.
     • Skripte für Training, Validierung und Inferenz.
     • Modellgewichte bei Änderung oder Feinabstimmung.
     • Konfigurationsdateien, Umgebungskonfigurationen (requirements.txt, Dockerfiles).
     • Backend- und Frontend-Code, wenn er Teil einer Webanwendung ist.
     • Alle Bibliotheken von Drittanbietern, die Sie geändert haben.
     • Trainingsdaten, falls erforderlich, zum Ausführen/Umlernen und zur Weitergabe.

4. Eindeutig dokumentieren:

   • Aktualisieren Sie Ihr README.md um anzugeben, dass das Projekt unter der AGPL-3.0 lizenziert ist.
   • Fügen Sie klare Anweisungen für das Einrichten, Erstellen und Ausführen Ihres Projekts anhand des Quellcodes bei.
   • Ordnen Sie Ultralytics YOLO entsprechend zu, indem Sie eine Verknüpfung zurück zur Originaldepot. Beispiel:

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

Beispiel einer Repository-Struktur

Eine praktische Beispielstruktur 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

Wenn Sie diese Richtlinien befolgen, stellen Sie die Einhaltung der AGPL-3.0 sicher und unterstützen das Open-Source-Ökosystem, das leistungsstarke Tools wie Ultralytics YOLO ermöglicht.

🎉 Schlussfolgerung

Vielen Dank für Ihr Interesse an der Mitwirkung an Ultralytics Open-Source-Projekten YOLO . Ihre Mitwirkung ist wichtig, um die Zukunft unserer Software zu gestalten und eine lebendige Gemeinschaft für Innovation und Zusammenarbeit aufzubauen. Ob Sie den Code verbessern, Fehler melden oder neue Funktionen vorschlagen, Ihre Beiträge sind von unschätzbarem Wert.

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

FAQ

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

Beiträge zu den Open-Source-Repositories Ultralytics YOLO verbessern die Software und machen sie für die gesamte Gemeinschaft robuster und funktionsreicher. Beiträge können Codeverbesserungen, Fehlerkorrekturen, Verbesserungen der Dokumentation und die Implementierung neuer Funktionen umfassen. Außerdem können Sie durch Ihre Beiträge mit anderen erfahrenen Entwicklern und Experten auf dem Gebiet zusammenarbeiten und so Ihre eigenen Fähigkeiten und Ihren Ruf verbessern. Einzelheiten zu den ersten Schritten finden Sie im Abschnitt Beiträge über Pull Requests.

Wie unterschreibe ich den Contributor License Agreement (CLA) für Ultralytics YOLO ?

Um die Lizenzvereinbarung für Mitwirkende (CLA) zu unterzeichnen, folgen Sie den Anweisungen des CLA-Bots, nachdem Sie Ihren Pull-Antrag eingereicht haben. Dieser Vorgang stellt sicher, dass Ihre Beiträge ordnungsgemäß unter der AGPL-3.0 Lizenz lizenziert werden und die rechtliche Integrität des Open-Source-Projekts gewahrt bleibt. Fügen Sie Ihrer Anfrage einen Kommentar hinzu, der angibt:

I have read the CLA Document and I sign the CLA

Weitere Informationen finden Sie im Abschnitt über die CLA-Signatur.

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

Google-Stil bieten eine klare, prägnante Dokumentation für Funktionen und Klassen und verbessern die Lesbarkeit und Wartbarkeit des Codes. Diese docstrings umreißen den Zweck der Funktion, die Argumente und die Rückgabewerte mit spezifischen Formatierungsregeln. Wenn Sie einen Beitrag zu Ultralytics YOLO leisten, stellen Sie durch die Einhaltung 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 Ihre Pull-Anfrage zusammengeführt werden kann, muss sie alle Tests von GitHub Actions Continuous Integration (CI) bestehen. Diese Tests umfassen Linting, Unit-Tests und andere Prüfungen, um sicherzustellen, dass der Code den Qualitätsstandards des Projekts entspricht. Überprüfen Sie die CI-Ausgabe und beheben Sie alle Probleme. Ausführliche Informationen über den CI-Prozess und Tipps zur Fehlerbehebung finden Sie im Abschnitt GitHub Actions CI-Tests.

Wie melde ich einen Fehler in den Repositories Ultralytics YOLO ?

Um einen Fehler zu melden, sollten Sie Ihrem Fehlerbericht ein klares und präzises , mindestens reproduzierbares Beispiel beifügen. Dies hilft den Entwicklern, das Problem schnell zu identifizieren und zu beheben. Stellen Sie sicher, dass Ihr Beispiel minimal, aber ausreichend ist, um das Problem zu reproduzieren. Ausführlichere Schritte zum Melden von Fehlern finden Sie im Abschnitt Fehler melden.

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

Wenn Sie Ultralytics YOLO oder -Modelle (die unter AGPL-3.0 lizenziert sind) in Ihrem Projekt verwenden, verlangt die AGPL-3.0 , dass Ihr gesamtes Projekt (das abgeleitete Werk) ebenfalls unter AGPL-3.0 lizenziert und sein vollständiger Quellcode öffentlich zugänglich gemacht wird. Dadurch wird sichergestellt, dass der Open-Source-Charakter der Software in allen Ableitungen erhalten bleibt. Wenn Sie diese Anforderungen nicht erfüllen können, müssen Sie eine Unternehmenslizenz erwerben. Weitere Informationen finden Sie im Abschnitt Open-Sourcing Ihres Projekts.

📅 Erstellt vor 1 Jahr ✏️ Aktualisiert vor 1 Monat

Kommentare