Contribuire ai progetti open source di Ultralytics#

Benvenuto! Siamo felicissimi che tu stia valutando di contribuire ai nostri progetti open-source di Ultralytics. Il tuo coinvolgimento non solo aiuta a migliorare la qualità dei nostri repository, ma avvantaggia anche l'intera comunità di computer vision. Questa guida fornisce linee guida chiare e best practice per aiutarti a iniziare.

🤝 Codice di condotta#

Per garantire un ambiente accogliente e inclusivo per tutti, tutti i contributori devono attenersi al nostro Code of Conduct. Rispetto, gentilezza e professionalità sono al centro della nostra community.

🚀 Contribuire tramite Pull Request#

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

1. Effettua il fork del repository: Inizia facendo 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 con fork usando 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 inviarle, testa le tue modifiche in locale per confermare che funzionino come previsto e non causino regressioni. Aggiungi dei test se stai introducendo nuove funzionalità.
5. Invia le tue modifiche (commit): Esegui il commit delle tue modifiche con messaggi concisi e descrittivi. Se le tue modifiche risolvono un problema specifico, includi il numero della issue (ad esempio, Fix #123: Corrected calculation error.).
6. Crea una pull request: Invia una pull request dal tuo branch al branch 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 di poter unire la tua pull request, devi firmare il nostro Contributor License Agreement (CLA). Questo accordo legale garantisce che i tuoi contributi siano concessi in licenza in modo appropriato, 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:

I have read the CLA Document and I sign the CLA

✍️ Docstring in stile Google#

Quando aggiungi nuove funzioni o classi, includi Google-style docstrings per una documentazione chiara e standardizzata. Racchiudi sempre sia l'input che l'output types 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

✅ Test CI di GitHub Actions#

Tutte le pull request devono superare i test di Continuous Integration (CI) di GitHub Actions prima di poter essere unite. Questi test includono linting, unit test e altri controlli per garantire che le tue modifiche soddisfino gli standard di qualità del progetto. Esamina l'output della CI e risolvi eventuali problemi che si presentano.

✨ 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 consistente: Strumenti come Ruff Formatter possono aiutarti a mantenere la coerenza stilistica.
• Aggiungi test appropriati: Includi test per le nuove funzionalità per assicurarti che funzionino come previsto.

👀 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 in che modo le modifiche potrebbero influire sulle prestazioni.
• Verifica i test della CI: Conferma che tutti i Continuous Integration tests 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.

🐞 Segnalazione di bug#

Diamo grande valore alle segnalazioni di bug in quanto 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 Minimum Reproducible Example: 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.

📜 Licenza#

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

🌍 Rendere open source il tuo progetto YOLO sotto AGPL-3.0#

Utilizzi modelli o codice di 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ù grandi basati su fondamenta open-source rimangano aperti.

Perché 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 il tuo progetto open-source, prendi in considerazione l'acquisto di una Enterprise License.

Come 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:

   • Effettua il fork di Ultralytics YOLO: Esegui direttamente il fork del repository di Ultralytics YOLO se basi il tuo lavoro strettamente su di esso.
   • Usa il template di Ultralytics: Inizia con il repository del template di Ultralytics per una configurazione pulita e modulare che integra YOLO.

2. Concedi in licenza il tuo progetto:

   • Aggiungi un file LICENSE contenente il testo integrale 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 dei modelli se modificati o ottimizzati (fine-tuned).
     • File di configurazione, impostazioni dell'ambiente (requirements.txt, Dockerfiles).
     • Codice backend e frontend se fa parte di una web application.
     • Eventuali librerie di terze parti che hai modificato.
     • Dati di training se necessari per l'esecuzione/il retraining 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 correttamente Ultralytics YOLO, inserendo un link di rimando 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#

Fa' riferimento al repository del 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.

Conclusione#

Grazie per il tuo interesse nel contribuire ai progetti open-source di Ultralytics open-source YOLO. La tua partecipazione è essenziale per plasmare il futuro del nostro software e costruire una vivace community di innovazione e collaborazione. Che tu stia migliorando il codice, segnalando bug o suggerendo nuove funzionalità, i tuoi contributi sono inestimabili.

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

FAQ#

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

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

Come 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:

I have read the CLA Document and I sign the CLA

Per ulteriori informazioni, consulta la sezione CLA Signing.

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

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

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. Rivedi 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 di bug. 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, 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 concesso in licenza anch'esso sotto AGPL-3.0 e il suo codice sorgente completo debba essere reso pubblico. Ciò garantisce che la natura open-source del software sia preservata in tutte le sue derivate. Se non puoi soddisfare questi requisiti, devi ottenere una Enterprise License. Consulta la sezione Open-Sourcing Your Project per i dettagli.