Link to this sectionContribuire 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.

Link to this section🤝 Codice di condotta#

Per garantire un ambiente accogliente e inclusivo per tutti, tutti i collaboratori devono attenersi al nostro Codice di Condotta. Rispetto, gentilezza e professionalità sono al centro della nostra comunità.

Link to this section🚀 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:

1. Effettua il fork del repository: inizia eseguendo il fork del repository Ultralytics pertinente (ad esempio, ultralytics/ultralytics) sul tuo account GitHub.
2. 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).
3. Apporta le tue modifiche: implementa i tuoi miglioramenti o correzioni. Assicurati che il tuo codice aderisca alle linee guida di stile del progetto e non introduca nuovi errori o avvisi.
4. Testa le tue modifiche: prima di inviare, testa le tue modifiche localmente per confermare che funzionino come previsto e non causino regressioni. Aggiungi dei test se stai introducendo nuove funzionalità.
5. Effettua il commit delle tue modifiche: Esegui il commit delle tue modifiche con messaggi di commit concisi e descrittivi. Se le tue modifiche risolvono un problema specifico, includi il numero del problema (ad esempio, Fix #123: Corrected calculation error.).
6. Crea una pull request: invia una pull request dal tuo branch al branch main del repository originale Ultralytics. Fornisci un titolo chiaro e una descrizione dettagliata che spieghi lo scopo e l'ambito delle tue modifiche.

Link to this section📝 Firma del CLA#

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

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

Link to this section✍️ Docstring in stile Google#

Quando aggiungi nuove funzioni o classi, includi docstring in stile Google per una documentazione chiara e standardizzata. Racchiudi sempre sia i types di input che di output tra parentesi (ad esempio, (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

Link to this section✅ 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.

Link to this section✨ 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 mirate 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, considera 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 i test appropriati: Includi test per le nuove funzionalità per assicurarti che funzionino come previsto.

Link to this section👀 Revisione delle Pull Request#

Revisionare le pull request è un altro modo prezioso per contribuire. Quando revisioni le PR:

• Controlla gli unit test: verifica che la PR includa test per nuove funzionalità o modifiche.
• Rivedi 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 vengano superati.
• Fornisci feedback costruttivo: offri feedback specifici e chiari su eventuali problemi o dubbi.
• Riconosci lo sforzo: apprezza il lavoro dell'autore per mantenere un'atmosfera collaborativa positiva.

Link to this section🐞 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 le 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 accadesse e cosa è successo effettivamente. Includi eventuali messaggi di errore o traceback.

Link to this section📜 Licenza#

Ultralytics utilizza la GNU Affero General Public License v3.0 (AGPL-3.0) per i suoi repository. Questa licenza promuove l'apertura, la trasparenza e il miglioramento collaborativo nello sviluppo del software. Garantisce che tutti gli utenti abbiano la libertà di utilizzare, modificare e condividere il software, favorendo una solida 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.

Link to this section🌍 Rendere open source il tuo progetto YOLO sotto AGPL-3.0#

Utilizzi modelli o codice YOLO di Ultralytics nel tuo progetto? La licenza AGPL-3.0 richiede che l'intera tua opera derivata sia anch'essa resa open source sotto AGPL-3.0. Questo garantisce che le modifiche e i progetti più grandi basati su fondamenta open source rimangano aperti.

Link to this sectionPerché la conformità alla AGPL-3.0 è importante#

• Mantiene il software aperto: garantisce che i miglioramenti e le opere derivate vadano a beneficio della comunità.
• Requisito legale: l'utilizzo di codice con licenza AGPL-3.0 vincola il tuo progetto ai suoi termini.
• Favorisce la collaborazione: incoraggia la condivisione e la trasparenza.

Se preferisci non rendere open source il tuo progetto, valuta di ottenere una Licenza Enterprise.

Link to this sectionCome conformarsi alla AGPL-3.0#

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

1. Scegli il tuo punto di partenza:

   • Fai il fork di YOLO di Ultralytics: effettua direttamente il fork del repository YOLO di Ultralytics se ci costruisci sopra molto da vicino.
   • Usa il template di Ultralytics: inizia con il repository template di Ultralytics per una configurazione pulita e modulare che integri YOLO.

2. 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.

3. Pubblica il tuo codice sorgente:

   • Rendi l'intero codice sorgente del tuo progetto accessibile pubblicamente (ad esempio, su GitHub). Questo include:
     • L'intera applicazione o sistema più grande che incorpora il modello o il codice YOLO.
     • Eventuali modifiche apportate al codice originale YOLO di Ultralytics.
     • Script per l'addestramento, la validazione e l'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 richiesti per eseguire/riaddestrare e ridistribuibili.

4. 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 YOLO di Ultralytics 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.

Link to this sectionEsempio 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à alla AGPL-3.0, supportando l'ecosistema open source che abilita strumenti potenti come YOLO di Ultralytics.

Link to this sectionConclusione#

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.

Link to this sectionFAQ#

Link to this sectionPerché dovrei contribuire ai repository open source di YOLO di Ultralytics?#

Contribuire ai repository open source di YOLO di Ultralytics migliora il software, rendendolo più solido 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 esperti ed esperti nel campo, migliorando le tue competenze e la tua reputazione. Per i dettagli su come iniziare, fai riferimento alla sezione Contribuire tramite Pull Request.

Link to this sectionCome posso firmare il Contratto di licenza del contributore (CLA) per YOLO di Ultralytics?#

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

Per ulteriori informazioni, consulta la sezione Firma del CLA.

Link to this sectionCosa sono le docstring in stile Google e perché sono richieste per i contributi a YOLO di Ultralytics?#

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 descrivono lo scopo della funzione, gli argomenti e i valori di ritorno con regole di formattazione specifiche. Quando contribuisci a YOLO di Ultralytics, seguire le docstring in stile Google assicura che le tue aggiunte siano ben documentate e facilmente comprensibili. Per esempi e linee guida, visita la sezione Docstring in stile Google.

Link to this sectionCome 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 risolvi eventuali problemi. Per informazioni dettagliate sul processo di CI e suggerimenti per la risoluzione dei problemi, consulta la sezione GitHub Actions CI Tests.

Link to this sectionCome posso segnalare un bug nei repository di Ultralytics YOLO?#

Per segnalare un bug, fornisci un Esempio Minimo Riproducibile chiaro e conciso insieme alla tua segnalazione. Questo aiuta gli sviluppatori a identificare e correggere rapidamente il problema. Assicurati che il tuo esempio sia minimo ma sufficiente a replicare il problema. Per passaggi più dettagliati sulla segnalazione dei bug, consulta la sezione Segnalazione Bug.

Link to this sectionCosa 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 relativo 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. Consulta la sezione Open-Sourcing Your Project per i dettagli.