Contribuer aux projets open source d’Ultralytics#

Bienvenue ! Nous sommes ravis que tu envisages de contribuer à nos projets Ultralytics open source. Ta participation contribue non seulement à améliorer la qualité de nos dépôts, mais bénéficie également à toute la communauté de la vision par ordinateur. Ce guide fournit des recommandations claires et des bonnes pratiques pour t’aider à démarrer.

Code de conduite#

Pour garantir un environnement accueillant et inclusif pour tout le monde, tous les contributeurs doivent respecter notre Code de conduite. Le respect, la bienveillance et le professionnalisme sont au cœur de notre communauté.

Contribuer via des PR#

Nous apprécions grandement les contributions sous forme de pull requests (PR). Pour faciliter au maximum le processus de revue, suis ces étapes :

1. Forker le dépôt : Commence par forker le dépôt Ultralytics concerné (par exemple, ultralytics/ultralytics) vers ton compte GitHub.
2. Créer une branche : Crée une nouvelle branche dans ton dépôt forké, avec un nom clair et descriptif reflétant tes modifications (par exemple, fix-issue-123, add-feature-xyz).
3. Apporter tes modifications : Implémente tes améliorations ou corrections. Vérifie que ton code respecte les conventions de style du projet et n’introduit pas de nouvelles erreurs ou avertissements.
4. Tester tes modifications : Avant l’envoi, teste tes modifications localement pour confirmer qu’elles fonctionnent comme prévu et ne provoquent pas de régressions. Ajoute des tests si tu introduis de nouvelles fonctionnalités.
5. Valider tes modifications : Valide tes modifications avec des messages de commit concis et descriptifs. Si tes modifications concernent un problème spécifique, inclus le numéro du problème (par exemple, Fix #123: Corrected calculation error.).
6. Créer une pull request : Soumets une pull request depuis ta branche vers la branche main du dépôt Ultralytics d’origine. Fournis un titre clair et une description détaillée expliquant l’objectif et la portée de tes modifications.

Installation pour le développement#

Clone ton fork (ou le dépôt principal) et installe-le en mode éditable (-e) pour que Python exécute tes fichiers locaux et prenne en compte chaque modification sans réinstallation :

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

Pour faire dépendre un autre projet d'un fork plutôt que du paquet PyPI, pointe pip ou requirements.txt vers la branche du fork :

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

Modifications de la documentation#

Le code source de la documentation se trouve dans docs/en/. Depuis la racine du dépôt, installe les dépendances de développement et exécute la validation stricte complète avant d’ouvrir une PR :

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

La validation prépare les références générées, les macros et les pages de comparaison avant d’exécuter zensical build --strict. Pour obtenir un aperçu en direct plus rapide des pages qui n’utilisent pas de macros, exécute zensical serve.

Signature du CLA#

Avant que nous puissions fusionner ta pull request, tu dois signer notre Accord de licence de contributeur (CLA). Cet accord juridique garantit que tes contributions sont correctement concédées sous licence, afin que le projet puisse continuer à être distribué sous la licence AGPL-3.0.

Après l’envoi de ta pull request, le bot CLA te guidera tout au long du processus de signature. Pour signer le CLA, ajoute simplement un commentaire dans ta PR indiquant :

I have read the CLA Document and I sign the CLA

Docstrings de style Google#

Lorsque tu ajoutes de nouvelles fonctions ou classes, inclus des docstrings au format Google afin de fournir une documentation claire et standardisée. Entoure toujours les types d’entrée et de sortie entre parenthèses (par exemple, (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

Tests CI GitHub Actions#

Toutes les pull requests doivent réussir les tests de GitHub Actions d’intégration continue (CI) avant de pouvoir être fusionnées. Ces tests comprennent l’analyse du style, les tests unitaires et d’autres vérifications visant à garantir que tes modifications respectent les standards de qualité du projet. Examine la sortie de la CI et corrige les problèmes éventuels.

Bonnes pratiques pour les contributions de code#

Lorsque tu contribues du code aux projets Ultralytics, garde ces bonnes pratiques à l’esprit :

• Évite la duplication de code : Réutilise le code existant lorsque c’est possible et réduis au minimum les arguments inutiles.
• Apporte des modifications ciblées et de petite taille : Concentre-toi sur des changements ciblés plutôt que sur des modifications de grande ampleur.
• Simplifie lorsque c’est possible : Cherche des occasions de simplifier le code ou de supprimer les éléments inutiles.
• Tiens compte de la compatibilité : Avant d’effectuer des modifications, demande-toi si elles risquent de casser du code existant utilisant Ultralytics.
• Utilise un formatage cohérent : Des outils comme Ruff Formatter peuvent contribuer à maintenir une cohérence stylistique.
• Ajoute des tests appropriés : Inclus des tests pour les nouvelles fonctionnalités afin de vérifier qu’elles fonctionnent comme prévu.

Examen des PR#

La revue des pull requests est une autre manière précieuse de contribuer. Lors de la revue des PR :

• Vérifie les tests unitaires : Vérifie que la PR inclut des tests pour les nouvelles fonctionnalités ou les modifications.
• Examine les mises à jour de la documentation : Vérifie que la documentation est mise à jour pour refléter les changements.
• Évalue l’impact sur les performances : Demande-toi comment les modifications pourraient affecter les performances.
• Vérifie les tests de CI : Confirme que tous les tests d’intégration continue réussissent.
• Fournis des retours constructifs : Donne des retours précis et clairs sur les problèmes ou préoccupations éventuels.
• Reconnais les efforts : Salue le travail de l’auteur afin de maintenir une atmosphère positive et collaborative.

Signaler des bugs#

Nous accordons une grande importance aux rapports de bugs, car ils nous aident à améliorer la qualité et la fiabilité de nos projets. Lorsque tu signales un bug via GitHub Issues :

• Vérifie les problèmes existants : Effectue d’abord une recherche pour voir si le bug a déjà été signalé.
• Fournis un exemple minimal reproductible : Crée un petit extrait de code autonome qui reproduit systématiquement le problème. Cela est essentiel pour faciliter le débogage.
• Décris l’environnement : Indique ton système d’exploitation, ta version de Python, les versions pertinentes des bibliothèques (par exemple, torch, ultralytics) et le matériel (CPU/GPU).
• Explique le comportement attendu et le comportement réel : Indique clairement ce qui devait se produire et ce qui s’est réellement produit. Inclus les messages d’erreur ou les traces d’exécution éventuels.

Licence#

Ultralytics utilise la Licence publique générale GNU Affero v3.0 (AGPL-3.0) pour ses dépôts. Cette licence favorise l’ouverture, la transparence et l’amélioration collaborative dans le développement logiciel. Elle garantit à tous les utilisateurs la liberté d’utiliser, de modifier et de partager le logiciel, favorisant ainsi une communauté forte fondée sur la collaboration et l’innovation.

Nous encourageons tous les contributeurs à se familiariser avec les conditions de la licence AGPL-3.0 afin de contribuer efficacement et éthiquement à la communauté open source d’Ultralytics.

Passer ton projet YOLO en open source sous AGPL-3.0#

Tu utilises des modèles ou du code YOLO d’Ultralytics dans ton projet ? La licence AGPL-3.0 exige que l’intégralité de ton œuvre dérivée soit également publiée sous AGPL-3.0. Cela garantit que les modifications et les projets plus vastes reposant sur des fondations open source restent ouverts.

Pourquoi le respect de l’AGPL-3.0 est important#

• Garde le logiciel ouvert : Garantit que les améliorations et les œuvres dérivées bénéficient à la communauté.
• Exigence légale : L’utilisation de code sous licence AGPL-3.0 soumet ton projet à ses conditions.
• Favorise la collaboration : Encourage le partage et la transparence.

Si tu préfères ne pas publier ton projet en open source, envisage d’obtenir une licence Enterprise.

Comment respecter l’AGPL-3.0#

Respecter cette licence signifie rendre l’intégralité du code source correspondant de ton projet publiquement disponible sous la licence AGPL-3.0.

1. Choisis ton point de départ :

   • Forke Ultralytics YOLO : Forke directement le dépôt Ultralytics YOLO si ton projet s’appuie étroitement dessus.
   • Utilise le modèle Ultralytics : Commence avec le dépôt modèle Ultralytics pour bénéficier d’une structure propre et modulaire intégrant YOLO.

2. Mets ton projet sous licence :

   • Ajoute un fichier LICENSE contenant le texte intégral de la licence AGPL-3.0.
   • Ajoute en haut de chaque fichier source une notice indiquant la licence.

3. Publie ton code source :

   • Rends l’intégralité du code source de ton projet publiquement accessible (par exemple, sur GitHub). Cela inclut :
     • L’application ou le système complet de plus grande ampleur qui intègre le modèle ou le code YOLO.
     • Toutes les modifications apportées au code Ultralytics YOLO d’origine.
     • Les scripts d’entraînement, de validation et d’inférence.
     • Les poids du modèle s’ils ont été modifiés ou ajustés.
     • Les fichiers de configuration et les configurations d’environnement (requirements.txt, Dockerfiles).
     • Le code backend et frontend s’il fait partie d’une application web.
     • Toutes les bibliothèques tierces que tu as modifiées.
     • Les données d’entraînement si elles sont nécessaires pour exécuter le modèle ou le réentraîner et si elles peuvent être redistribuées.

4. Documente clairement :

   • Mets à jour ton fichier README.md pour indiquer que le projet est sous licence AGPL-3.0.
   • Inclus des instructions claires pour configurer, compiler et exécuter ton projet à partir du code source.
   • Attribue correctement Ultralytics YOLO en renvoyant vers le dépôt d’origine. Exemple :

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

Exemple de structure de dépôt#

Consulte le dépôt modèle Ultralytics pour voir un exemple concret de structure :

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

En suivant ces recommandations, tu garantis le respect de l’AGPL-3.0 et soutiens l’écosystème open source qui permet de créer des outils puissants comme Ultralytics YOLO.

Conclusion#

Merci de ton intérêt pour les projets YOLO Ultralytics open source. Ta participation est essentielle pour façonner l’avenir de nos logiciels et construire une communauté dynamique d’innovation et de collaboration. Que tu améliores du code, signales des bugs ou proposes de nouvelles fonctionnalités, tes contributions sont inestimables.

Nous avons hâte de voir tes idées prendre vie et nous apprécions ton engagement à faire progresser la technologie de détection d’objets. Ensemble, continuons à grandir et à innover dans cette aventure open source passionnante.

FAQ#