Contribuer aux projets open source d'Ultralytics

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

🤝 Code de conduite

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

🚀 Contribuer via des Pull Requests

Nous apprécions grandement les contributions sous forme de pull requests (PRs). Pour rendre le processus de revue aussi fluide que possible, merci de suivre ces étapes :

1. Forker le dépôt : Commence par forker le dépôt Ultralytics pertinent (par ex. ultralytics/ultralytics) sur 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 changements (par ex. fix-issue-123, add-feature-xyz).
3. Apporter tes modifications : Implémente tes améliorations ou correctifs. Assure-toi que ton code respecte les directives de style du projet et ne crée pas de nouvelles erreurs ou avertissements.
4. Tester tes modifications : Avant de soumettre, teste tes modifications localement pour confirmer qu'elles fonctionnent comme prévu et ne causent pas de régressions. Ajoute des tests si tu introduis une nouvelle fonctionnalité.
5. Commit your changes: Commit your changes with concise and descriptive commit messages. If your changes address a specific issue, include the issue number (e.g., 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 le but et la portée de tes modifications.

📝 Signature du CLA

Avant que nous puissions fusionner ta pull request, tu dois signer notre Contributor License Agreement (CLA). Cet accord juridique garantit que tes contributions sont correctement licenciées, permettant au projet de continuer à être distribué sous la licence AGPL-3.0.

Après avoir soumis 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 en indiquant :

✍️ Docstrings de style Google

Lors de l'ajout de nouvelles fonctions ou classes, inclus des docstrings de style Google pour une documentation claire et standardisée. Encloses toujours les types d'entrée et de sortie entre parenthèses (par ex. (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

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

✨ Bonnes pratiques pour les contributions de code

Lors de la contribution de code aux projets Ultralytics, garde ces bonnes pratiques à l'esprit :

• Évite la duplication de code : Réutilise le code existant autant que possible et minimise les arguments inutiles.
• Apporte des modifications petites et ciblées : Concentre-toi sur des modifications précises plutôt que sur des changements à grande échelle.
• Simplifie quand c'est possible : Cherche des opportunités de simplifier le code ou de supprimer les parties inutiles.
• Considère la compatibilité : Avant d'apporter des modifications, considère si elles pourraient casser le code existant utilisant Ultralytics.
• Utilise un formatage cohérent : Des outils comme Ruff Formatter peuvent aider à maintenir une cohérence stylistique.
• Ajoute des tests appropriés : Inclue des tests pour les nouvelles fonctionnalités afin d'assurer qu'elles fonctionnent comme prévu.

👀 Revue de pull requests

Revoir les pull requests est une autre façon précieuse de contribuer. Lors de la revue de PRs :

• Vérifie les tests unitaires : Vérifie que la PR inclut des tests pour les nouvelles fonctionnalités ou changements.
• Revois les mises à jour de la documentation : Assure-toi que la documentation est mise à jour pour refléter les changements.
• Évalue l'impact sur les performances : Considère comment les changements pourraient affecter la performance.
• Vérifie les tests CI : Confirme que tous les tests d'Intégration Continue réussissent.
• Fournis un retour constructif : Offre des retours spécifiques et clairs sur tout problème ou préoccupation.
• Reconnais les efforts : Salue le travail de l'auteur pour maintenir une atmosphère collaborative positive.

🐞 Signaler des bugs

Nous apprécions énormément les rapports de bugs car ils nous aident à améliorer la qualité et la fiabilité de nos projets. Lors du signalement d'un bug via GitHub Issues :

• Vérifie les issues existantes : Cherche d'abord si le bug a déjà été rapporté.
• Fournis un Exemple Minimum Reproductible : Crée un petit extrait de code autonome qui reproduit systématiquement le problème. C'est crucial pour un débogage efficace.
• Décris l'environnement : Spécifie ton système d'exploitation, ta version de Python, les versions des bibliothèques pertinentes (par ex. torch, ultralytics) et le matériel (CPU/GPU).
• Explique le comportement attendu vs réel : Énonce clairement ce que tu attendais et ce qui s'est réellement produit. Inclue tout message d'erreur ou traceback.

📜 Licence

Ultralytics utilise la GNU Affero General Public License v3.0 (AGPL-3.0) pour ses dépôts. Cette licence promeut l'ouverture, la transparence et l'amélioration collaborative dans le développement logiciel. Elle garantit que tous les utilisateurs ont la liberté d'utiliser, modifier et partager le logiciel, favorisant ainsi une solide communauté de collaboration et d'innovation.

Nous encourageons tous les contributeurs à se familiariser avec les termes de la licence AGPL-3.0 afin de contribuer de manière efficace et éthique à la communauté open source d'Ultralytics.

🌍 Mettre 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'ensemble de ton œuvre dérivée soit également en open source sous AGPL-3.0. Cela garantit que les modifications et les projets plus vastes construits sur des fondations open source restent ouverts.

Pourquoi la conformité à l'AGPL-3.0 est importante

• Maintient le logiciel ouvert : Assure que les améliorations et œuvres dérivées profitent à la communauté.
• Exigence légale : Utiliser du code sous licence AGPL-3.0 lie ton projet à ses termes.
• Favorise la collaboration : Encourage le partage et la transparence.

Si tu préfères ne pas mettre ton projet en open source, envisage d'obtenir une Licence Entreprise.

Comment se conformer à l'AGPL-3.0

Se conformer signifie rendre le code source correspondant complet de ton projet publiquement disponible sous la licence AGPL-3.0.

1. Choisis ton point de départ :

   • Forker Ultralytics YOLO : Forke directement le dépôt Ultralytics YOLO si tu construis étroitement autour.
   • Utiliser le modèle Ultralytics : Commence avec le dépôt de modèle Ultralytics pour une configuration propre et modulaire intégrant YOLO.

2. Licencie ton projet :

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

3. Publie ton code source :

   • Rends l'intégralité du code source de ton projet publiquement accessible (par ex. sur GitHub). Cela inclut :
     • L'application ou le système global complet qui intègre le modèle ou le code YOLO.
     • Toute modification apportée au code original d'Ultralytics YOLO.
     • Les scripts d'entraînement, de validation et d'inférence.
     • Les poids des modèles s'ils sont modifiés ou ajustés (fine-tuned).
     • Les fichiers de configuration, 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 nécessaires pour exécuter/ré-entraîner et redistribuables.

4. Documente clairement :

   • Mets à jour ton README.md pour indiquer que le projet est sous licence AGPL-3.0.
   • Inclue des instructions claires sur la façon de configurer, construire et exécuter ton projet à partir du code source.
   • Attribue Ultralytics YOLO de manière appropriée, en liant vers le dépôt original. 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

Référe-toi au Dépôt de modèle Ultralytics pour une structure d'exemple pratique :

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 directives, tu assures la conformité avec l'AGPL-3.0, en soutenant l'écosystème open source qui permet des outils puissants comme Ultralytics YOLO.

Conclusion

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

Nous sommes impatients de voir tes idées prendre vie et 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

Pourquoi devrais-je contribuer aux dépôts open source d'Ultralytics YOLO ?

Contribuer aux dépôts open source d'Ultralytics YOLO améliore le logiciel, le rendant plus robuste et riche en fonctionnalités pour toute la communauté. Les contributions peuvent inclure des améliorations de code, des correctifs de bugs, des améliorations de documentation et l'implémentation de nouvelles fonctionnalités. De plus, contribuer te permet de collaborer avec d'autres développeurs qualifiés et experts du domaine, améliorant ainsi tes propres compétences et ta réputation. Pour plus de détails sur la façon de commencer, réfère-toi à la section Contribuer via des Pull Requests.

Comment puis-je signer le Contributor License Agreement (CLA) pour Ultralytics YOLO ?

Pour signer le Contributor License Agreement (CLA), suis les instructions fournies par le bot CLA après avoir soumis ta pull request. Ce processus garantit que tes contributions sont correctement licenciées sous la licence AGPL-3.0, maintenant l'intégrité juridique du projet open source. Ajoute un commentaire dans ta pull request en indiquant :

Pour plus d'informations, voir la section Signature du CLA.

Qu'est-ce que les docstrings de style Google et pourquoi sont-elles requises pour les contributions à Ultralytics YOLO ?

Les docstrings de style Google fournissent une documentation claire et concise pour les fonctions et les classes, améliorant la lisibilité et la maintenabilité du code. Ces docstrings décrivent l'objectif, les arguments et les valeurs de retour de la fonction avec des règles de formatage spécifiques. Lors de la contribution à Ultralytics YOLO, suivre les docstrings de style Google garantit que tes ajouts sont bien documentés et facilement compréhensibles. Pour des exemples et des directives, visite la section Docstrings de style Google.

Comment puis-je m'assurer que mes modifications réussissent les tests CI de GitHub Actions ?

Avant que ta pull request ne puisse être fusionnée, elle doit réussir tous les tests d'intégration continue (CI) de GitHub Actions. Ces tests incluent le linting, les tests unitaires et d'autres vérifications pour garantir que le code respecte les normes de qualité du projet. Examine le résultat de la CI et corrige tout problème. Pour des informations détaillées sur le processus CI et des conseils de dépannage, consulte la section GitHub Actions CI Tests.

Comment signaler un bug dans les dépôts Ultralytics YOLO ?

Pour signaler un bug, fournis un Minimum Reproducible Example clair et concis avec ton rapport de bug. Cela aide les développeurs à identifier et corriger rapidement le problème. Assure-toi que ton exemple est minimal tout en étant suffisant pour reproduire le souci. Pour des étapes plus détaillées sur le signalement des bugs, réfère-toi à la section Reporting Bugs.

Que signifie la licence AGPL-3.0 si j'utilise Ultralytics YOLO dans mon propre projet ?

Si tu utilises du code ou des modèles Ultralytics YOLO (sous licence AGPL-3.0) dans ton projet, la licence AGPL-3.0 exige que l'intégralité de ton projet (l'œuvre dérivée) soit également sous licence AGPL-3.0 et que son code source complet soit rendu public. Cela garantit que la nature open-source du logiciel est préservée dans ses dérivés. Si tu ne peux pas remplir ces conditions, tu dois obtenir une Enterprise License. Consulte la section Open-Sourcing Your Project pour plus de détails.