Contribuer aux projets open source 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 profite aussi à toute la communauté de la vision par ordinateur. Ce guide présente des consignes claires et des bonnes pratiques pour t’aider à démarrer.

Code de conduite#

Pour garantir un environnement accueillant et inclusif pour tout le monde, chaque personne contribuant au projet doit respecter notre Code de conduite. Le respect, la bienveillance et le professionnalisme sont au cœur de notre communauté.

Contribuer par des pull requests#

Nous apprécions grandement les contributions sous forme de pull requests (PR). Pour que le processus de revue se déroule aussi facilement que possible, suis les étapes suivantes :

1. Forker le dépôt : commence par forker le dépôt Ultralytics concerné (par exemple, ultralytics/ultralytics) sur ton compte GitHub.
2. Créer une branche : crée une branche dans ton dépôt forké en lui donnant un nom clair et descriptif qui reflète tes modifications (par exemple, fix-issue-123, add-feature-xyz).
3. Effectuer tes modifications : apporte 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 alertes.
4. Tester tes modifications : avant de soumettre ta contribution, teste tes modifications localement pour vérifier 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 : crée un commit avec un message concis et descriptif. Si tes modifications répondent à un problème précis, indique le numéro du problème (par exemple, Fix #123: Corrected calculation error.).
6. Créer une pull request : soumets une pull request de ta branche vers la branche main du dépôt Ultralytics d’origine. Choisis un titre clair et rédige 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) afin que Python utilise 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 qu’un autre projet dépende d’un fork plutôt que du paquet PyPI, indique à pip ou à requirements.txt la branche du fork :

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

Modifications de la documentation#

Les sources de la documentation se trouvent 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 prévisualiser plus rapidement en direct les 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 contribution (CLA). Cet accord juridique garantit que tes contributions sont dûment 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 à ta PR indiquant :

I have read the CLA Document and I sign the CLA

Docstrings au format Google#

Lorsque tu ajoutes de nouvelles fonctions ou classes, inclue des docstrings au format Google pour obtenir une documentation claire et standardisée. Place 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 avec 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 statique, les tests unitaires et d’autres vérifications visant à garantir que tes modifications respectent les normes de qualité du projet. Examine les résultats de la CI et corrige les problèmes éventuels.

Bonnes pratiques pour les contributions au code#

Lorsque tu contribues au code des projets Ultralytics, garde à l’esprit les bonnes pratiques suivantes :

• Évite la duplication de code : réutilise le code existant autant que possible et limite les arguments superflus.
• Privilégie les modifications ciblées et de petite taille : concentre-toi sur des changements précis plutôt que sur des modifications à grande échelle.
• Simplifie dans la mesure du possible : cherche des occasions de simplifier le code ou d’en supprimer les éléments inutiles.
• Tiens compte de la compatibilité : avant d’effectuer des modifications, demande-toi si elles risquent de casser le code existant qui utilise Ultralytics.
• Utilise une mise en forme cohérente : des outils comme Ruff Formatter peuvent t’aider à maintenir une cohérence stylistique.
• Ajoute des tests appropriés : ajoute des tests pour les nouvelles fonctionnalités afin de vérifier qu’elles fonctionnent comme prévu.

Revue des pull requests#

La revue des pull requests est une autre façon précieuse de contribuer. Lors de la revue d’une PR :

• Vérifie la présence de tests unitaires : vérifie que la PR inclut des tests pour les nouvelles fonctionnalités ou modifications.
• Examine les mises à jour de la documentation : vérifie que la documentation a été mise à jour pour refléter les modifications.
• Évalue les répercussions 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 commentaires constructifs : signale les problèmes ou les préoccupations de manière précise et claire.
• Reconnais les efforts : souligne le travail de l’auteur afin de maintenir une atmosphère de collaboration positive.

Signaler des bugs#

Nous accordons une grande importance aux signalements 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 : commence par rechercher 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. C’est essentiel pour déboguer efficacement.
• Décris l’environnement : indique ton système d’exploitation, ta version de Python, les versions des bibliothèques concernées (par exemple, torch, ultralytics) et ton matériel (CPU/GPU.
• Explique le comportement attendu et le comportement réel : indique clairement ce que tu t’attendais à voir et ce qui s’est réellement produit. Ajoute tous les messages d’erreur ou traces de pile.

Licence#

Ultralytics utilise la Licence publique générale GNU Affero, version 3.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é solide axé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 de manière éthique à la communauté open source d’Ultralytics.

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

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

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

• Maintient les logiciels en accès libre : garantit que les améliorations et les œuvres dérivées profitent à la communauté.
• Obligation 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 la licence signifie rendre public le code source complet correspondant de ton projet sous licence AGPL-3.0.

1. Choisis ton point de départ :

   • Fork le dépôt Ultralytics YOLO : fork directement le dépôt Ultralytics YOLO si ton projet s’en inspire étroitement.
   • Utilise le modèle Ultralytics : commence avec le dépôt de modèles Ultralytics pour disposer d’une structure propre et modulaire intégrant YOLO.

2. Place ton projet sous licence :

   • Ajoute un fichier LICENSE contenant le texte intégral de la licence AGPL-3.0.
   • Ajoute un avis en haut de chaque fichier source pour indiquer la licence.

3. Publie ton code source :

   • Rends accessible au public l’intégralité du code source de ton projet (par exemple, sur GitHub). Cela comprend :
     • L’application ou le système complet de plus grande envergure 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 à l’exécution ou au réentraînement et peuvent être redistribuées.

4. Documente clairement :

   • Mets à jour ton README.md pour indiquer que le projet est sous licence AGPL-3.0.
   • Ajoute des instructions claires expliquant comment configurer, compiler et exécuter ton projet à partir du code source.
   • Attribue correctement Ultralytics YOLO en ajoutant un lien 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 de modèles 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 respectes 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 l’intérêt que tu portes à la contribution aux projets YOLO Ultralytics open source. Ta participation est essentielle pour façonner l’avenir de nos logiciels et bâtir une communauté dynamique, axée sur l’innovation et la collaboration. Que tu améliores du code, signales des bugs ou proposes de nouvelles fonctionnalités, tes contributions sont précieuses.

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

FAQ#