Contribuire ai progetti open source di Ultralytics#

Benvenuto! Siamo entusiasti che tu stia prendendo in considerazione l'idea di contribuire ai nostri progetti Ultralytics open source. Il tuo coinvolgimento non solo contribuisce a migliorare la qualità dei nostri repository, ma porta vantaggi anche all'intera community della 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, ogni contributore deve attenersi al nostro Codice di condotta. Rispetto, gentilezza e professionalità sono alla base della nostra community.

Contribuire tramite PR#

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

1. Crea un fork del repository: Inizia creando un fork del repository Ultralytics pertinente (ad esempio, ultralytics/ultralytics) nel tuo account GitHub.
2. Crea un branch: Crea un nuovo branch nel repository di cui hai creato il fork, usando un nome chiaro e descrittivo che rifletta le modifiche (ad esempio, fix-issue-123, add-feature-xyz).
3. Apporta le modifiche: Implementa i tuoi miglioramenti o le tue 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 localmente le modifiche per verificare che funzionino come previsto e non causino regressioni. Aggiungi test se stai introducendo 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 dell'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 modifiche.

Installazione per lo sviluppo#

Clona il tuo fork (o il repository principale) e installalo in modalità modificabile (-e) in modo che Python esegua i tuoi file locali e recepisca ogni modifica senza 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, punta pip o requirements.txt al branch del fork:

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

Modifiche alla documentazione#

Il codice sorgente della documentazione si trova in docs/en/. Dalla radice del repository, installa le dipendenze di sviluppo ed esegui la convalida completa in modalità strict 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 fare il merge della tua pull request, devi firmare il nostro Accordo di licenza per i contributori (CLA). Questo accordo legale garantisce che i tuoi contributi siano concessi in licenza correttamente, consentendo al progetto di continuare a essere distribuito secondo 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 con il seguente testo:

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 types di input sia quello di output (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 per l'integrazione continua (CI) prima di poter essere unite. Questi test includono linting, test delle unità e altri controlli per garantire che le modifiche rispettino gli standard di qualità del progetto. Esamina l'output della CI e risolvi gli eventuali problemi.

Best practice per i contributi di codice#

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

• Evita la duplicazione del codice: Riutilizza il codice esistente ogni volta che è possibile e riduci al minimo gli argomenti non necessari.
• Apporta modifiche più piccole e mirate: Concentrati su modifiche circoscritte anziché 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 compromettere il codice esistente che usa Ultralytics.
• Usa una formattazione coerente: 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 PR#

La revisione delle pull request è un altro modo prezioso per contribuire. Quando esamini le PR:

• Controlla i test delle unità: Verifica 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 della CI: Conferma che tutti i test di integrazione continua siano superati.
• Fornisci feedback costruttivo: Offri un feedback specifico e chiaro su eventuali problemi o dubbi.
• Riconosci l'impegno: Riconosci il lavoro dell'autore per mantenere un'atmosfera collaborativa positiva.

Segnalazione di bug#

Attribuiamo grande valore alle 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 coerente. È fondamentale per un debugging efficiente.
• Descrivi l'ambiente: Specifica il sistema operativo, la versione di Python, le versioni delle librerie pertinenti (ad esempio, torch, ultralytics) e l'hardware (CPU/GPU).
• Spiega il comportamento previsto rispetto a quello effettivo: Indica chiaramente cosa ti aspettavi che accadesse e cosa è accaduto realmente. Includi eventuali messaggi di errore o traceback.

Licenza#

Ultralytics utilizza la Licenza Pubblica Generica Affero GNU v3.0 (AGPL-3.0) per i propri repository. Questa licenza promuove apertura, trasparenza e [miglioramento collaborativo](https://ultralytics-translation-3.invalid nello sviluppo del software. Garantisce a tutti gli utenti la libertà di usare, modificare e condividere il software, favorendo una community forte di collaborazione e innovazione.

Invitiamo 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 con licenza AGPL-3.0#

Usi modelli o codice YOLO di Ultralytics nel tuo progetto? La licenza AGPL-3.0 richiede che anche l'intera opera derivata sia resa open source secondo AGPL-3.0. In questo modo, le modifiche e i progetti più grandi costruiti su basi open source rimangono aperti.

Perché la conformità ad AGPL-3.0 è importante#

• Mantiene aperto il software: Garantisce che i miglioramenti e le opere derivate siano vantaggiosi per la community.
• Requisito 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 rendere open source il tuo progetto, valuta la possibilità di ottenere una licenza Enterprise.

Come conformarsi ad AGPL-3.0#

Essere conformi significa rendere pubblicamente disponibile il codice sorgente completo corrispondente del tuo progetto secondo la licenza AGPL-3.0.

1. Scegli il punto di partenza:

   • Crea un fork di Ultralytics YOLO: Crea direttamente un fork del repository Ultralytics YOLO se stai costruendo il tuo progetto basandoti strettamente su di esso.
   • Usa il template Ultralytics: Inizia dal repository template di Ultralytics per una configurazione pulita e modulare che integri YOLO.

2. Concedi una licenza al tuo progetto:

   • Aggiungi un file LICENSE contenente il testo completo della licenza AGPL-3.0.
   • Aggiungi un avviso all'inizio di ogni file sorgente indicando la licenza.

3. Pubblica il codice sorgente:

   • Rendi accessibile pubblicamente l'intero codice sorgente del tuo progetto (ad esempio, su GitHub). Questo include:
     • L'applicazione o il sistema completo e più ampio che incorpora il modello o il codice YOLO.
     • Qualsiasi modifica apportata al codice Ultralytics YOLO originale.
     • Script per l'addestramento, la validazione e l'inferenza.
     • I pesi del modello se modificati o sottoposti a fine-tuning.
     • File di configurazione, configurazioni dell'ambiente (requirements.txt, Dockerfiles).
     • Codice backend e frontend se fanno parte di un'applicazione web.
     • Qualsiasi libreria di terze parti che hai modificato.
     • Dati di addestramento se necessari per eseguire nuovamente l'addestramento e redistribuibili.

4. Documenta chiaramente:

   • Aggiorna il tuo README.md per dichiarare che il progetto è distribuito secondo la licenza AGPL-3.0.
   • Includi istruzioni chiare su come configurare, compilare ed eseguire il tuo progetto dal codice sorgente.
   • Attribuisci correttamente Ultralytics YOLO, rimandando al repository originale. Esempio:

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

Struttura di esempio del repository#

Consulta il Repository template di 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, garantisci la conformità ad AGPL-3.0 e sostieni l'ecosistema open source che rende possibili strumenti potenti come Ultralytics YOLO.

Conclusioni#

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

Non vediamo l'ora di vedere le tue idee diventare realtà e apprezziamo il tuo impegno nel far progredire la tecnologia di rilevamento degli oggetti. Insieme, continuiamo a crescere e innovare in questo entusiasmante percorso open source.

FAQ#