Contribuire ai progetti open source di Ultralytics

Benvenuti! Siamo entusiasti che stiate prendendo in considerazione l'idea di contribuire alla nostra Ultralytics open-source. Il vostro coinvolgimento non solo contribuisce a migliorare la qualità dei nostri repository, ma va anche a beneficio dell'intera comunità di computer vision. Questa guida fornisce linee guida chiare e buone pratiche per aiutarvi a iniziare.

Guarda: Come contribuire al repository di 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 richieste di pull

Apprezziamo moltissimo i contributi sotto forma di richieste di modifica (PR). Per rendere il processo di revisione il più agevole possibile, si prega di seguire i seguenti passaggi:

1. Creare un fork del repository: Iniziare con il fork del repository Ultralytics pertinente (ad esempio, ultralytics) sul proprio account GitHub.
2. Creare un ramo: Creare un nuovo ramo nel repository biforcato con un nome chiaro e descrittivo che rifletta le modifiche apportate (ad es, fix-issue-123, add-feature-xyz).
3. Apportare le modifiche: Implementate i vostri miglioramenti o le vostre correzioni. Assicuratevi che il codice sia conforme alle linee guida di stile del progetto e che non introduca nuovi errori o avvisi.
4. Testate le modifiche: Prima di inviare le modifiche, testatele in locale per verificare che funzionino come previsto e non causino regressioni. Aggiungete dei test se state introducendo nuove funzionalità.
5. Impegnare le modifiche: Impegnare le 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. Creare una richiesta di pull: Inviare una richiesta di pull dal proprio ramo al file main del repository originale di Ultralytics . Fornire un titolo chiaro e una descrizione dettagliata che spieghi lo scopo e la portata delle modifiche.

📝 Firma CLA

Prima di poter unire la vostra richiesta di pull, dovete firmare il nostro Contributor License Agreement (CLA). Questo accordo legale garantisce che i vostri contributi siano correttamente autorizzati, consentendo al progetto di continuare a essere distribuito sotto la licenzaAGPL-3.0 .

Dopo aver inviato la richiesta di pull, il bot CLA vi guiderà nel processo di firma. Per firmare il CLA, è sufficiente aggiungere un commento nella propria PR che indichi:

I have read the CLA Document and I sign the CLA

✍️ Docstring Google

Quando si aggiungono nuove funzioni o classi, includere Documenti Google per una documentazione chiara e standardizzata. Allegare sempre sia l'input che l'output types tra parentesi (ad es, (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

Azioni GitHub Test CI

Tutte le richieste di pull devono superare i test di GitHub Actions Continuous Integration (CI) prima di poter essere unite. Questi test includono linting, test unitari e altri controlli per garantire che le modifiche soddisfino gli standard di qualità del progetto. Esaminate i risultati della CI e risolvete eventuali problemi.

✨ Migliori pratiche per i contributi al codice

Quando si contribuisce al codice dei progetti Ultralytics , è bene tenere a mente queste buone pratiche:

• Evitare la duplicazione del codice: Riutilizzare il codice esistente quando possibile e ridurre al minimo gli argomenti non necessari.
• Apportare modifiche più piccole e mirate: Concentratevi su modifiche mirate piuttosto che su cambiamenti su larga scala.
• Semplificare quando è possibile: Cercare le opportunità per semplificare il codice o eliminare le parti non necessarie.
• Considerare la compatibilità: Prima di apportare modifiche, valutare se queste potrebbero interrompere il codice esistente che utilizza Ultralytics.
• Utilizzare una formattazione coerente: Strumenti come Ruff Formatter possono aiutare a mantenere la coerenza stilistica.
• Aggiungere test appropriati: Includere i test per le nuove funzionalità per garantire che funzionino come previsto.

👀 Revisione delle richieste di pull

La revisione delle richieste di pull è un altro modo prezioso per contribuire. Quando si revisionano le PR:

• Verificare la presenza di test unitari: Verificare che la PR includa i test per le nuove funzionalità o modifiche.
• Esaminare gli aggiornamenti della documentazione: Assicurarsi che la documentazione sia aggiornata per riflettere le modifiche.
• Valutare l'impatto sulle prestazioni: Considerare il modo in cui le modifiche potrebbero influire sulle prestazioni.
• Verifica dei test CI: Confermare il superamento di tutti i test di Continuous Integration.
• Fornire un feedback costruttivo: Offrite un feedback specifico e chiaro su qualsiasi problema o preoccupazione.
• Riconoscere lo sforzo: Riconoscere il lavoro dell'autore per mantenere un'atmosfera di collaborazione positiva.

🐞 Segnalazione di bug

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

• Controllare i problemi esistenti: Cercare prima di tutto se il bug è già stato segnalato.
• Fornire un esempio minimo riproducibile: Creare un piccolo frammento di codice autonomo che riproduca in modo coerente il problema. Questo è fondamentale per un debugging efficiente.
• Descrivere l'ambiente: Specificare il sistema operativo, la versione di Python , le versioni delle librerie pertinenti (ad es, torch, ultralytics) e hardware (CPU/GPU).
• Spiegare il comportamento previsto e quello effettivo: Indicare chiaramente cosa ci si aspettava che accadesse e cosa si è effettivamente verificato. Includere 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 a tutti gli utenti la libertà di utilizzare, modificare e condividere il software, favorendo una forte comunità di collaborazione e innovazione.

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

🌍 Open-Sourcing del progetto YOLO sotto AGPL-3.0

Utilizzate i modelli o il codiceYOLO Ultralytics nel vostro progetto? La licenzaAGPL-3.0 richiede che l'intero lavoro derivato sia anch'esso open-sourcing sotto AGPL-3.0. Questo garantisce che le modifiche e i progetti più ampi costruiti su basi open-source rimangano aperti.

Perché è importante la conformità alla AGPL-3.0

• Mantiene il software aperto: Assicura che i miglioramenti e le opere derivate vadano a beneficio della comunità.
• Requisiti legali: L'utilizzo di codice con licenza AGPL-3.0 vincola il progetto ai suoi termini.
• Favorisce la collaborazione: Incoraggia la condivisione e la trasparenza.

Se non volete ricorrere all'open-source per il vostro progetto, prendete in considerazione la possibilità di ottenere una licenza Enterprise.

Come rispettare la licenza AGPL-3.0

Conformarsi significa rendere disponibile al pubblico il codice sorgente completo e corrispondente del progetto sotto la licenza AGPL-3.0 .

1. Scegliere il punto di partenza:

   • Forkare Ultralytics YOLO: fare direttamente il fork del repositoryUltralytics YOLO se si costruisce strettamente su di esso.
   • Utilizzare il modello Ultralytics : Iniziare con il repository di templateUltralytics per una configurazione pulita e modulare che integri YOLO.

2. Concessione di licenza per il progetto:

   • Aggiungere un LICENSE contenente il testo completo del documento Licenza AGPL-3.0.
   • Aggiungere un avviso all'inizio di ogni file sorgente che indichi la licenza.

3. Pubblicare il codice sorgente:

   • Fate in modo che il vostro il codice sorgente dell'intero progetto accessibili pubblicamente (ad esempio, su GitHub). Questo include:
     • L'applicazione o il sistema completo più grande che incorpora il modello o il codice YOLO .
     • Qualsiasi modifica apportata al codice originale di Ultralytics YOLO .
     • Script per addestramento, validazione e inferenza.
     • Pesi del modello se modificati o messi a punto.
     • File di configurazione, impostazioni dell'ambiente (requirements.txt, Dockerfiles).
     • Codice backend e frontend se fa parte di un'applicazione web.
     • Eventuali librerie di terze parti modificate.
     • Dati di addestramento se necessari per l'esecuzione/il riaddestramento e ridistribuibili.

4. Documento chiaro:

   • Aggiornate il vostro README.md per dichiarare che il progetto è concesso in licenza AGPL-3.0.
   • Includere istruzioni chiare su come impostare, costruire ed eseguire il progetto dal codice sorgente.
   • Attribuire a Ultralytics YOLO in modo appropriato, con un collegamento al file deposito originale. Esempio:

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

Esempio di struttura del repository

Per un esempio pratico di struttura, consultare il Repository dei modelliUltralytics :

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, si garantisce la conformità alla AGPL-3.0, sostenendo l'ecosistema open-source che consente di utilizzare strumenti potenti come Ultralytics YOLO.

🎉 Conclusione

Grazie per il vostro interesse a contribuire ai progetti Ultralytics progetti open-source di YOLO . La vostra partecipazione è essenziale per plasmare il futuro del nostro software e costruire una comunità vibrante di innovazione e collaborazione. Che si tratti di migliorare il codice, segnalare bug o suggerire nuove funzionalità, i vostri contributi sono preziosi.

Siamo entusiasti di vedere le vostre idee prendere vita e apprezziamo il vostro impegno nel far progredire la tecnologia di rilevamento degli oggetti. Insieme, continuiamo a crescere e a innovare in questo entusiasmante viaggio 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, il contributo consente di collaborare con altri sviluppatori ed esperti del settore, migliorando le proprie capacità e la propria reputazione. Per i dettagli su come iniziare, consultare la sezione Contribuire tramite richieste di prelievo.

Come si firma il Contributor License Agreement (CLA) per Ultralytics YOLO ?

Per firmare il Contributor License Agreement (CLA), seguire le istruzioni fornite dal bot CLA dopo aver inviato la richiesta di pull. Questo processo assicura che i vostri contributi siano correttamente concessi in licenza secondo la licenza AGPL-3.0 , mantenendo l'integrità legale del progetto open-source. Aggiungere un commento nella richiesta di pull indicando:

I have read the CLA Document and I sign the CLA

Per ulteriori informazioni, consultare la sezione Firma CLA.

Cosa sono le docstrazioni in stile Google e perché sono richieste per i contributi Ultralytics YOLO ?

Google-Le docstringhe in stile forniscono una documentazione chiara e concisa per le funzioni e le classi, migliorando la leggibilità e la manutenibilità del codice. Queste documentazioni descrivono lo scopo della funzione, gli argomenti e i valori di ritorno con regole di formattazione specifiche. Quando si contribuisce a Ultralytics YOLO , seguire i docstring in stile Google assicura che le aggiunte siano ben documentate e facilmente comprensibili. Per esempi e linee guida, visitare la sezione Google-Style Docstrings.

Come posso assicurarmi che le mie modifiche superino i test di GitHub Actions CI?

Prima che la richiesta di pull possa essere unita, deve superare tutti i test di GitHub Actions Continuous Integration (CI). Questi test includono linting, test unitari e altri controlli per garantire che il codice soddisfi gli standard di qualità del progetto. Esaminare i risultati della CI e correggere eventuali problemi. Per informazioni dettagliate sul processo di CI e suggerimenti per la risoluzione dei problemi, consultare la sezione Test CI di GitHub Actions.

Come posso segnalare un bug nei repository di Ultralytics YOLO ?

Per segnalare un bug, fornire un esempio minimo riproducibile chiaro e conciso insieme alla segnalazione del bug. Questo aiuta gli sviluppatori a identificare e risolvere rapidamente il problema. Assicurarsi che l'esempio sia minimo ma sufficiente per replicare il problema. Per informazioni più dettagliate sulla segnalazione dei bug, consultare la sezione Segnalazione dei bug.

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

Se si utilizza il codice o i modelli di Ultralytics YOLO (con licenza AGPL-3.0) nel proprio 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 disponibile al pubblico. In questo modo si garantisce che la natura open-source del software sia preservata in tutti i suoi derivati. Se non è possibile soddisfare questi requisiti, è necessario ottenere una licenza Enterprise. Per maggiori dettagli, consultare la sezione Open-Sourcing del progetto.

📅C reato 1 anno fa ✏️ Aggiornato 1 mese fa

Commenti