Contribuire ai progetti open source di Ultralytics

Benvenuti! Siamo entusiasti che tu stia considerando di contribuire ai nostri progetti Ultralytics open-source. 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.

Guarda: Come contribuire al repository Ultralytics | Modelli, dataset e documentazione Ultralytics 🚀

🤝 Codice di condotta

Per garantire un ambiente accogliente e inclusivo per tutti, tutti i collaboratori devono aderire 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ù agevole possibile, segui questi passaggi:

1. Fork the repository: Inizia effettuando 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 forked 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. Esegui il commit delle modifiche: Esegui il commit delle modifiche con messaggi di commit concisi e descrittivi. Se le modifiche riguardano un problema specifico, includere il numero del problema (ad esempio, Fix #123: Corrected calculation error.).
6. Crea una pull request: Invia una pull request dal tuo branch al main branch del repository Ultralytics originale. Fornisci un titolo chiaro e una descrizione dettagliata che spieghi lo scopo e l'ambito delle tue modifiche.

📝 Firma CLA

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

Dopo aver inviato la pull request, il bot CLA ti guiderà attraverso il processo di firma. Per firmare il CLA, è sufficiente aggiungere un commento nella tua PR con la seguente dicitura:

I have read the CLA Document and I sign the CLA

✍️ Docstring in stile Google

Quando si aggiungono nuove funzioni o classi, includere Docstring in stile Google per una documentazione chiara e standardizzata. Racchiudere 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

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

def example_function(arg1: int, arg2: int = 4) -> bool:
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ Test CI di GitHub Actions

Tutte le pull request devono superare i test di GitHub Actions Integrazione Continua (CI) 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. Rivedi l'output CI e risolvi eventuali problemi che si presentano.

✨ Best practice per i contributi al codice

Quando si contribuisce con codice ai progetti Ultralytics, tenere a mente queste best practice:

• Evitare la duplicazione del codice: Riusare il codice esistente ove possibile e ridurre al minimo gli argomenti non necessari.
• Apportare 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.
• Utilizza una formattazione coerente: Strumenti come Ruff Formatter possono aiutare a mantenere la coerenza stilistica.
• Aggiungere test appropriati: Includere test per le nuove funzionalità per garantire che funzionino come previsto.

👀 Revisione delle pull request

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

• Verifica la presenza di unit test: Verifica che la PR includa test per nuove funzionalità o modifiche.
• Aggiornamenti della documentazione di revisione: Assicurarsi che la documentazione sia aggiornata per riflettere le modifiche.
• Valutare l'impatto sulle prestazioni: Considera come le modifiche potrebbero influire sulle prestazioni.
• Verifica dei test CI: Conferma che tutti i test di integrazione continua siano superati.
• Fornisci un feedback costruttivo: Offri un feedback specifico e chiaro su eventuali problemi o preoccupazioni.
• Riconoscere l'impegno: Riconoscere il lavoro dell'autore per mantenere un'atmosfera collaborativa positiva.

🐞 Segnalazione di bug

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

• Verifica 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.
• Descrivere l'ambiente: Specifica il tuo sistema operativo, la versione di Python, le versioni delle librerie rilevanti (ad es. torch, ultralytics), e hardware (CPU/GPU).
• Spiega il comportamento previsto rispetto a quello effettivo: Indica chiaramente cosa ti aspettavi 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 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, promuovendo una forte comunità di collaborazione e innovazione.

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

🌍 Open-sourcing del tuo progetto YOLO con licenza AGPL-3.0

Utilizzi modelli o codice Ultralytics YOLO nel tuo progetto? La licenza AGPL-3.0 richiede che anche l'intero tuo lavoro derivato sia open source sotto AGPL-3.0. Ciò garantisce che le modifiche e i progetti più grandi costruiti su fondamenta open source rimangano aperti.

Perché la conformità AGPL-3.0 è importante

• Mantiene il software aperto: Assicura 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.
• Promuove 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 rispettare AGPL-3.0

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

1. Scegli il tuo punto di partenza:

   • Fork di Ultralytics YOLO: Esegui direttamente il fork del repository Ultralytics YOLO se lo stai costruendo strettamente su di esso.
   • Utilizza il template Ultralytics: Inizia con il repository template di Ultralytics per una configurazione pulita e modulare che integra YOLO.

2. Licenza del tuo progetto:

   • Aggiungi un LICENSE file contenente il testo completo del Licenza AGPL-3.0.
   • Aggiungi un avviso nella parte superiore di ogni file sorgente che indichi la licenza.

3. Pubblica il tuo codice sorgente:

   • Crea il tuo codice sorgente dell'intero progetto pubblicamente accessibile (ad esempio, su GitHub). Questo include:
     • L'applicazione o il sistema completo più ampio che incorpora il modello o il codice YOLO.
     • Qualsiasi modifica apportata al codice Ultralytics YOLO originale.
     • Script per l'addestramento, la convalida, 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 una applicazione web.
     • Qualsiasi libreria di terze parti che hai modificato.
     • Dati di addestramento se richiesto per eseguire/riaddestrare e ridistribuibile.

4. Documentare in modo chiaro:

   • Aggiorna il tuo README.md per dichiarare che il progetto è concesso in licenza con AGPL-3.0.
   • Includi istruzioni chiare su come impostare, compilare ed eseguire il tuo progetto dal codice sorgente.
   • Attribuire correttamente Ultralytics YOLO, con un link di rimando a repository originale. Esempio:

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

Esempio di struttura di repository

Fare riferimento all'Ultralytics Template Repository 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, ti assicuri la conformità con AGPL-3.0, supportando l'ecosistema open-source che abilita strumenti potenti come Ultralytics YOLO.

🎉 Conclusione

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

Siamo entusiasti di vedere le vostre idee prendere vita e apprezziamo il vostro impegno per far progredire la tecnologia di object detection. Insieme, continuiamo a crescere e innovare in questo entusiasmante percorso open-source. Buon coding! 🚀🌟

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 esperti ed esperti del settore, migliorando le tue capacità e la tua reputazione. Per i dettagli su come iniziare, consulta la sezione Contribuire tramite Pull Request.

Come posso firmare il Contratto di Licenza del Contributore (CLA) per Ultralytics YOLO?

Per firmare il Contributor License Agreement (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 con 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 maggiori informazioni, consultare la sezione sulla Firma 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, gli argomenti e i valori di ritorno della funzione con regole di formattazione specifiche. Quando si contribuisce a Ultralytics YOLO, seguire le docstring in stile Google assicura che le 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 Integrazione Continua (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 di CI e suggerimenti per la risoluzione dei problemi, consulta la sezione Test CI di GitHub Actions.

Come posso segnalare un bug nei repository 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 per replicare il problema. Per passaggi più dettagliati sulla segnalazione di bug, consulta la sezione Segnalazione di Bug.

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

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

📅 Creato 1 anno fa ✏️ Aggiornato 2 mesi fa

Commenti