Contribuire ai progetti open source Ultralytics#

Benvenuto! Ci fa molto piacere che tu stia pensando di contribuire ai nostri progetti Ultralytics open source. Il tuo contributo non solo aiuta a migliorare la qualità dei nostri repository, ma è utile anche all'intera community di computer vision. Questa guida offre indicazioni chiare e buone pratiche per aiutarti a iniziare.

Codice di condotta#

Per garantire un ambiente accogliente e inclusivo per tutti, ogni contributore deve rispettare il nostro Codice di condotta. Rispetto, gentilezza e professionalità sono i pilastri della nostra community.

Contribuire tramite pull request#

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

1. Crea un fork del repository: inizia creando un fork del repository Ultralytics pertinente (ad esempio, ultralytics/ultralytics) sul tuo account GitHub.
2. Crea un branch: crea un nuovo branch nel repository di cui hai creato un fork, assegnandogli un nome chiaro e descrittivo che rispecchi le modifiche (ad esempio, fix-issue-123, add-feature-xyz).
3. Apporta le modifiche: implementa i miglioramenti o le correzioni. Assicurati che il codice rispetti le linee guida di stile del progetto e non introduca nuovi errori o avvisi.
4. Testa le modifiche: prima dell'invio, testa le modifiche in locale per verificare che funzionino come previsto e non causino regressioni. Aggiungi test se introduci nuove funzionalità.
5. Esegui il commit delle modifiche: esegui il commit delle modifiche con messaggi concisi e descrittivi. Se le 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 Ultralytics originale. Inserisci un titolo chiaro e una descrizione dettagliata che spieghi lo scopo e l'ambito delle modifiche.

Installazione per lo sviluppo#

Clona il tuo fork (o il repository principale) e installalo in modalità modificabile (-e), così Python esegue i tuoi file locali e recepisce ogni modifica senza dover reinstallare:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Per fare in modo che un altro progetto dipenda da un fork anziché dal pacchetto PyPI, indirizza pip o requirements.txt al branch del fork:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Modifiche alla documentazione#

I sorgenti della documentazione si trovano in docs/en/. Dalla radice del repository, installa le dipendenze di sviluppo ed esegui la convalida rigorosa completa prima di aprire una PR:

uv pip install -e ".[dev]"
python docs/build_docs.py

La convalida prepara i riferimenti generati, le macro e le pagine di confronto prima di eseguire zensical build --strict. Per un'anteprima live più rapida delle pagine che non usano macro, esegui zensical serve.

Firma del CLA#

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

Dopo aver inviato la pull request, il bot CLA ti guiderà nella procedura di firma. Per firmare il CLA, ti basta aggiungere un commento alla tua PR con il testo seguente:

I have read the CLA Document and I sign the CLA

Docstring in stile Google#

Quando aggiungi nuove funzioni o classi, includi docstring in stile Google per una documentazione chiara e standardizzata. Racchiudi sempre tra parentesi sia l'input sia l'output types (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 GitHub Actions di integrazione continua (CI) prima di poter essere unite. Questi test includono linting, test unitari e altri controlli per assicurare che le modifiche soddisfino gli standard di qualità del progetto. Esamina l'output CI e risolvi gli eventuali problemi.

Buone pratiche per contribuire al codice#

Quando contribuisci con codice ai progetti Ultralytics, tieni presenti queste buone pratiche:

• Evita la duplicazione del codice: riutilizza il codice esistente ogni volta che è possibile e riduci al minimo gli argomenti non necessari.
• Apporta modifiche mirate e di piccola entità: concentrati su modifiche circoscritte anziché su interventi 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 compromettere il codice esistente che usa Ultralytics.
• Usa una formattazione coerente: strumenti come Ruff Formatter possono aiutarti a mantenere uno stile uniforme.
• Aggiungi test adeguati: includi test per le nuove funzionalità e assicurati che funzionino come previsto.

Revisione delle pull request#

Anche revisionare le pull request è un modo prezioso per contribuire. Quando esamini le PR:

• Verifica la presenza di test unitari: controlla che la PR includa test per le 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 in che modo le modifiche potrebbero influire sulle prestazioni.
• Verifica i test CI: conferma che tutti i test di integrazione continua siano superati.
• Fornisci feedback costruttivi: segnala in modo specifico e chiaro eventuali problemi o dubbi.
• Riconosci l'impegno: riconosci il lavoro dell'autore per mantenere un clima collaborativo positivo.

Segnalazione dei bug#

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

• Controlla le issue esistenti: cerca prima per verificare se il bug è già stato segnalato.
• Fornisci un esempio minimo riproducibile: crea un piccolo frammento di codice autonomo che riproduca il problema in modo costante. È essenziale per eseguire il debug in modo efficiente.
• Descrivi l'ambiente: specifica il sistema operativo, la versione di Python, le versioni delle librerie pertinenti (ad es. torch, ultralytics) e l'hardware (CPU/GPU).
• Spiega il comportamento previsto e quello effettivo: indica chiaramente cosa ti aspettavi che accadesse e cosa è successo. Includi eventuali messaggi di errore o traceback.

Licenza#

Ultralytics utilizza la Licenza pubblica generale Affero GNU v3.0 (AGPL-3.0) per i propri repository. Questa licenza promuove l'apertura, la trasparenza e il miglioramento collaborativo nello sviluppo software. Garantisce a tutti gli utenti la libertà di utilizzare, modificare e condividere il software, favorendo una solida comunità basata sulla collaborazione e sull'innovazione.

Invitiamo tutti i collaboratori a familiarizzare con i termini della licenza AGPL-3.0, così da contribuire in modo efficace ed etico alla comunità open source di Ultralytics.

Rilasciare il tuo progetto YOLO come open source con AGPL-3.0#

Usi i modelli o il codice Ultralytics YOLO nel tuo progetto? La licenza AGPL-3.0 richiede che anche l'intera opera derivata venga rilasciata come open source con AGPL-3.0. Questo garantisce che le modifiche e i progetti più ampi basati su fondamenta open source rimangano aperti.

Perché è importante rispettare la licenza AGPL-3.0#

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

Se preferisci non rilasciare il tuo progetto come open source, valuta la possibilità di ottenere una licenza Enterprise.

Come rispettare la licenza AGPL-3.0#

Per rispettare la licenza, devi rendere pubblicamente disponibile con licenza AGPL-3.0 il codice sorgente completo corrispondente del tuo progetto.

1. Scegli da dove iniziare:

   • Crea un fork di Ultralytics YOLO: crea direttamente un fork del repository Ultralytics YOLO se il tuo progetto si basa strettamente su di esso.
   • Usa il modello Ultralytics: inizia dal repository del modello Ultralytics per una struttura pulita e modulare che integri YOLO.

2. Scegli la licenza per 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 per indicare la licenza.

3. Pubblica il codice sorgente:

   • Rendi accessibile pubblicamente il codice sorgente completo del tuo progetto (ad es. su GitHub). Questo include:
     • L'intera applicazione o sistema più ampio che integra il modello o il codice YOLO.
     • Qualsiasi modifica apportata al codice originale di Ultralytics YOLO.
     • Gli script per l'addestramento, la convalida e l'inferenza.
     • I pesi del modello, se modificati o sottoposti a fine-tuning.
     • I file di configurazione e le configurazioni dell'ambiente (requirements.txt, Dockerfiles).
     • Il codice backend e frontend, se fa parte di un'applicazione web.
     • Qualsiasi libreria di terze parti che hai modificato.
     • I dati di addestramento, se necessari per l'esecuzione o il nuovo addestramento e ridistribuibili.

4. Documenta chiaramente:

   • Aggiorna il tuo README.md per specificare che il progetto è distribuito con licenza AGPL-3.0.
   • Includi istruzioni chiare per configurare, compilare ed eseguire il progetto a partire dal codice sorgente.
   • Attribuisci correttamente Ultralytics YOLO e inserisci un link 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#

Consulta il repository del modello Ultralytics per un esempio pratico di struttura:

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, rispetti la licenza AGPL-3.0 e sostieni l'ecosistema open source che rende possibili strumenti potenti come Ultralytics YOLO.

Conclusione#

Grazie per il tuo interesse nel contribuire ai progetti YOLO open source di Ultralytics. La tua partecipazione è essenziale per plasmare il futuro del nostro software e costruire una vivace comunità di innovazione e collaborazione. Che tu migliori il codice, segnali bug o suggerisca nuove funzionalità, i tuoi contributi sono preziosi.

Non vediamo l'ora di vedere le tue idee prendere forma e apprezziamo il tuo impegno nel far progredire la tecnologia di rilevamento degli oggetti. Continuiamo insieme a crescere e innovare in questo entusiasmante percorso open source.

Domande frequenti#