Contribuire ai progetti open source di Ultralytics

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

🤝 Codice di condotta

Per garantire un ambiente accogliente e inclusivo per tutti, ogni collaboratore deve attenersi al nostro Codice di condotta. Rispetto, gentilezza e professionalità sono al centro della nostra comunità.

🚀 Contribuire tramite Pull Request

Apprezziamo molto i contributi sotto forma di pull request (PR). Per rendere il processo di revisione il più fluido possibile, segui questi passaggi:

Fai il fork del repository: Inizia eseguendo il fork del repository Ultralytics pertinente (ad esempio, ultralytics/ultralytics) sul tuo account GitHub.
Crea un branch: Crea un nuovo branch nel tuo repository forkato con un nome chiaro e descrittivo che rifletta le tue modifiche (ad esempio, fix-issue-123, add-feature-xyz).
Apporta le tue modifiche: Implementa i miglioramenti o le correzioni. Assicurati che il tuo codice rispetti le linee guida di stile del progetto e non introduca nuovi errori o avvisi.
Testa le tue modifiche: Prima di inviare, testa le tue modifiche localmente per confermare che funzionino come previsto e non causino regressioni. Aggiungi test se stai introducendo nuove funzionalità.
Commit your changes: Commit your changes with concise and descriptive commit messages. If your changes address a specific issue, include the issue number (e.g., Fix #123: Corrected calculation error.).
Crea una pull request: Invia una pull request dal tuo branch a quello main del repository Ultralytics originale. Fornisci un titolo chiaro e una descrizione dettagliata che spieghi lo scopo e l'ambito delle tue modifiche.

📝 Firma del CLA

Prima che possiamo unire la tua pull request, devi firmare il nostro Contratto di licenza del contributore (CLA). Questo accordo legale garantisce che i tuoi contributi siano correttamente concessi in licenza, consentendo al progetto di continuare a essere distribuito sotto licenza AGPL-3.0.

Dopo aver inviato la tua pull request, il bot CLA ti guiderà attraverso il processo di firma. Per firmare il CLA, aggiungi semplicemente un commento nella tua PR indicando:

I have read the CLA Document and I sign the CLA

✍️ Docstring in stile Google

When adding new functions or classes, include Google-style docstrings for clear, standardized documentation. Always enclose both input and output types in parentheses (e.g., (bool), (np.ndarray)).

Esempio di docstring

Questo esempio illustra il formato standard della docstring in stile Google. Nota come separa chiaramente la descrizione della funzione, gli argomenti, il valore restituito e gli esempi per la massima leggibilità.

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

✅ Test CI di GitHub Actions

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

✨ Best practice per i contributi di codice

Quando contribuisci con codice ai progetti Ultralytics, tieni a mente queste best practice:

Evita la duplicazione del codice: Riutilizza il codice esistente ove possibile e riduci al minimo gli argomenti non necessari.
Apporta modifiche più piccole e mirate: Concentrati su modifiche specifiche piuttosto che su cambiamenti su larga scala.
Semplifica quando possibile: Cerca opportunità per semplificare il codice o rimuovere parti non necessarie.
Considera la compatibilità: Prima di apportare modifiche, valuta se potrebbero interrompere il codice esistente che utilizza Ultralytics.
Usa una formattazione coerente: Strumenti come Ruff Formatter possono aiutare a mantenere la coerenza stilistica.
Aggiungi test appropriati: Includi test per le nuove funzionalità per assicurarti che funzionino come previsto.

👀 Revisione delle Pull Request

La revisione delle pull request è un altro modo prezioso per contribuire. Durante la revisione delle PR:

Controlla gli unit test: Verifica che la PR includa test per nuove funzionalità o modifiche.
Esamina gli aggiornamenti della documentazione: Assicurati che la documentazione sia aggiornata per riflettere le modifiche.
Valuta l'impatto sulle prestazioni: Considera come le modifiche potrebbero influire sulle prestazioni.
Verifica i test CI: Conferma che tutti i test di Continuous Integration siano superati.
Fornisci feedback costruttivo: Offri feedback specifici e chiari su eventuali problemi o dubbi.
Riconosci l'impegno: Dai atto al lavoro dell'autore per mantenere un'atmosfera collaborativa positiva.

🐞 Segnalazione di bug

Apprezziamo molto le segnalazioni di bug poiché ci aiutano a migliorare la qualità e l'affidabilità dei nostri progetti. Quando segnali un bug tramite GitHub Issues:

Controlla i problemi esistenti: Cerca prima per vedere se il bug è già stato segnalato.
Fornisci un Esempio minimo riproducibile: Crea un piccolo frammento di codice autonomo che riproduca costantemente il problema. Questo è fondamentale per un debug efficiente.
Descrivi l'ambiente: Specifica il tuo sistema operativo, la versione di Python, le versioni delle librerie pertinenti (ad esempio, torch, ultralytics) e l'hardware (CPU/GPU).
Spiega il comportamento atteso rispetto a quello effettivo: Indica chiaramente cosa ti aspettavi che accadesse e cosa è successo realmente. Includi eventuali messaggi di errore o traceback.

📜 Licenza

Ultralytics utilizza la GNU Affero General Public License v3.0 (AGPL-3.0) per i suoi repository. Questa licenza promuove apertura, trasparenza e miglioramento collaborativo nello sviluppo del software. Garantisce che tutti gli utenti abbiano la libertà di utilizzare, modificare e condividere il software, favorendo una forte comunità di collaborazione e innovazione.

Incoraggiamo tutti i contributori a familiarizzare con i termini della licenza AGPL-3.0 per contribuire in modo efficace ed etico alla comunità open-source di Ultralytics.

🌍 Rendi open-source il tuo progetto YOLO sotto AGPL-3.0

Usi modelli o codice Ultralytics YOLO nel tuo progetto? La licenza AGPL-3.0 richiede che l'intera opera derivata sia anch'essa open-source sotto AGPL-3.0. Questo garantisce che le modifiche e i progetti più ampi costruiti su basi open-source rimangano aperti.

Perché la conformità ad AGPL-3.0 è importante

Mantiene il software aperto: Garantisce che i miglioramenti e le opere derivate vadano a beneficio della comunità.
Requisito legale: L'uso di codice con licenza AGPL-3.0 vincola il tuo progetto ai suoi termini.
Promuove la collaborazione: Incoraggia la condivisione e la trasparenza.

Se preferisci non rendere open-source il tuo progetto, valuta l'ottenimento di una Licenza Enterprise.

Come conformarsi alla licenza AGPL-3.0

Conformarsi significa rendere il codice sorgente corrispondente completo del proprio progetto pubblicamente disponibile sotto la licenza AGPL-3.0.

Scegli il tuo punto di partenza:
- Fai il fork di Ultralytics YOLO: Fai direttamente il fork del repository di Ultralytics YOLO se stai costruendo qualcosa basato strettamente su di esso.
- Usa il template di Ultralytics: Inizia con il repository template di Ultralytics per una configurazione pulita e modulare che integra YOLO.
Concedi in licenza il tuo progetto:
- Aggiungi un file LICENSE contenente il testo completo della licenza AGPL-3.0.
- Aggiungi un avviso in cima a ogni file sorgente che indichi la licenza.
Pubblica il tuo codice sorgente:
- Rendi l'intero codice sorgente del tuo progetto accessibile pubblicamente (ad esempio, su GitHub). Questo include:
  - L'applicazione o il sistema più ampio completo che incorpora il modello o il codice YOLO.
  - Eventuali modifiche apportate al codice originale Ultralytics YOLO.
  - Script per addestramento, validazione e inferenza.
  - Pesi del modello se modificati o ottimizzati.
  - File di configurazione, configurazioni dell'ambiente (requirements.txt, Dockerfiles).
  - Codice backend e frontend se fa parte di un'applicazione web.
  - Eventuali librerie di terze parti che hai modificato.
  - Dati di addestramento se necessari per eseguire/riaddestrare e ridistribuibili.
Documenta chiaramente:
- Aggiorna il tuo README.md per dichiarare che il progetto è concesso in licenza sotto AGPL-3.0.
- Includi istruzioni chiare su come configurare, compilare ed eseguire il tuo progetto dal codice sorgente.
- Attribuisci Ultralytics YOLO in modo appropriato, collegandoti al repository originale. Esempio:
```
This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.
```

Esempio di struttura del repository

Fai riferimento al Repository Template di Ultralytics per una struttura di esempio pratica:

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

Seguendo queste linee guida, garantisci la conformità con AGPL-3.0, supportando l'ecosistema open-source che consente strumenti potenti come Ultralytics YOLO.

Conclusione

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

Siamo entusiasti di vedere le tue idee prendere vita e apprezziamo il tuo impegno nel far progredire la tecnologia di rilevamento oggetti. Insieme, continuiamo a crescere e innovare in questo entusiasmante viaggio open-source.

FAQ

Perché dovrei contribuire ai repository open-source di Ultralytics YOLO?

Contribuire ai repository open-source di Ultralytics YOLO migliora il software, rendendolo più robusto e ricco di funzionalità per l'intera comunità. I contributi possono includere miglioramenti del codice, correzioni di bug, miglioramenti della documentazione e implementazioni di nuove funzionalità. Inoltre, contribuire ti consente di collaborare con altri sviluppatori ed esperti del settore, migliorando le tue competenze e la tua reputazione. Per i dettagli su come iniziare, fai riferimento alla sezione Contribuire tramite Pull Request.

Come firmo il Contratto di licenza del contributore (CLA) per Ultralytics YOLO?

Per firmare il Contratto di licenza del contributore (CLA), segui le istruzioni fornite dal bot CLA dopo aver inviato la tua pull request. Questo processo garantisce che i tuoi contributi siano correttamente concessi in licenza sotto la licenza AGPL-3.0, mantenendo l'integrità legale del progetto open-source. Aggiungi un commento nella tua pull request indicando:

I have read the CLA Document and I sign the CLA

Per ulteriori informazioni, consulta la sezione Firma del CLA.

Cosa sono le docstring in stile Google e perché sono richieste per i contributi a Ultralytics YOLO?

Le docstring in stile Google forniscono una documentazione chiara e concisa per funzioni e classi, migliorando la leggibilità e la manutenibilità del codice. Queste docstring delineano lo scopo della funzione, gli argomenti e i valori restituiti con regole di formattazione specifiche. Quando contribuisci a Ultralytics YOLO, seguire le docstring in stile Google garantisce che le tue aggiunte siano ben documentate e facilmente comprensibili. Per esempi e linee guida, visita la sezione Docstring in stile Google.

Come posso assicurarmi che le mie modifiche superino i test CI di GitHub Actions?

Prima che la tua pull request possa essere unita, deve superare tutti i test di Continuous Integration (CI) di GitHub Actions. Questi test includono linting, unit test e altri controlli per garantire che il codice soddisfi gli standard di qualità del progetto. Esamina l'output della CI e correggi eventuali problemi. Per informazioni dettagliate sul processo CI e suggerimenti per la risoluzione dei problemi, consulta la sezione GitHub Actions CI Tests.

Come posso segnalare un bug nei repository di Ultralytics YOLO?

Per segnalare un bug, fornisci un Minimum Reproducible Example chiaro e conciso insieme alla tua segnalazione. Questo aiuta gli sviluppatori a identificare e risolvere rapidamente il problema. Assicurati che il tuo esempio sia minimo ma sufficiente per replicare il problema. Per passaggi più dettagliati sulla segnalazione di bug, fai riferimento alla sezione Reporting Bugs.

Cosa significa la licenza AGPL-3.0 se utilizzo Ultralytics YOLO nel mio progetto?

Se utilizzi codice o modelli di Ultralytics YOLO (con licenza AGPL-3.0) nel tuo progetto, la licenza AGPL-3.0 richiede che l'intero progetto (l'opera derivata) debba essere anch'esso concesso in licenza sotto AGPL-3.0 e che il suo codice sorgente completo debba essere reso disponibile pubblicamente. Ciò garantisce che la natura open-source del software sia preservata in tutti i suoi derivati. Se non puoi soddisfare questi requisiti, devi ottenere una Enterprise License. Vedi la sezione Open-Sourcing Your Project per i dettagli.

Contributors

GLglenn-jocher²² RIRizwanMunawar³ PDpderrenger¹ Y-Y-T-G¹WIWillie Maddox¹LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

Created 12 nov 2023Updated settimana scorsa