Contribuer aux projets open-source d'Ultralytics#

Bienvenue ! Nous sommes ravis que tu envisages de contribuer à nos projets open-source Ultralytics. Ton implication aide non seulement à améliorer la qualité de nos dépôts, mais profite également à toute la communauté computer vision. Ce guide fournit des directives claires et des bonnes pratiques pour t'aider à démarrer.

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

🤝 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 Pull Requests#

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

Fait un fork du dépôt : Commence par faire un fork du dépôt Ultralytics concerné (par exemple, ultralytics/ultralytics) sur ton compte GitHub.
Crée 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).
Effectue tes changements : Implémente tes améliorations ou correctifs. Assure-toi que ton code respecte les directives de style du projet et ne génère pas de nouvelles erreurs ou avertissements.
Teste 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 de nouvelles fonctionnalités.
Valide tes modifications (commit) : Valide tes modifications avec des messages de commit concis et descriptifs. Si tes modifications résolvent un problème spécifique, inclus le numéro du problème (par exemple, Fix #123: Corrected calculation error.).
Crée une pull request : Soumets une pull request de 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.

📝 Signature du CLA#

Avant que nous puissions fusionner ta pull request, tu dois signer notre Contributeur License Agreement (CLA). Cet accord juridique garantit que tes contributions sont correctement sous licence, 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 indiquant :

I have read the CLA Document and I sign the CLA

✍️ Docstrings de style Google#

Lors de l'ajout de nouvelles fonctions ou classes, inclus des docstrings de style Google pour une documentation claire et normalisée. Entoure toujours les types d'entrée et de sortie par des parenthèses (par exemple, (bool), (np.ndarray)).

Exemples de Docstrings

Cet exemple illustre le format standard de docstring de style Google. Note comment il sépare clairement la description de la fonction, les arguments, la valeur de retour et les exemples pour une lisibilité maximale.

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 Continuous Integration (CI) de GitHub Actions avant de pouvoir être fusionnées. Ces tests incluent le lintage, les tests unitaires et d'autres vérifications pour s'assurer que tes modifications répondent aux normes de qualité du projet. Examine la sortie de la CI et résous tout problème qui se présente.

✨ Meilleures 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 chaque fois que possible et minimise les arguments inutiles.
Fais des changements plus petits et ciblés : Concentre-toi sur des modifications ciblées plutôt que sur des changements à grande échelle.
Simplifie quand c'est possible : Recherche des opportunités pour simplifier le code ou supprimer des parties inutiles.
Considère la compatibilité : Avant de faire des changements, considère s'ils pourraient briser le code existant utilisant Ultralytics.
Utilise un formatage cohérent : Des outils comme Ruff Formatter peuvent aider à maintenir la cohérence stylistique.
Ajoute des tests appropriés : Inclus des tests pour les nouvelles fonctionnalités afin de t'assurer qu'elles fonctionnent comme prévu.

👀 Revue des Pull Requests#

La revue de 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 inclue des tests pour les nouvelles fonctionnalités ou changements.
Examine les mises à jour de la documentation : Assure-toi que la documentation est mise à jour pour refléter les modifications.
Évalue l'impact sur les performances : Examine comment les modifications peuvent affecter les performances.
Vérifie les tests de CI : Confirme que tous les tests d'intégration continue réussissent.
Fournis des feedbacks constructifs : Offre des retours spécifiques et clairs sur tout problème ou préoccupation.
Reconnais les efforts : Reconnais le travail de l'auteur pour maintenir une atmosphère collaborative positive.

🐞 Signaler des bugs#

Nous accordons une grande valeur aux 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 problèmes existants : Cherche d'abord à voir si le bug a déjà été signalé.
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 de bibliothèques pertinentes (par exemple, torch, ultralytics) et ton matériel (CPU/GPU).
Explique le comportement attendu vs actuel : Indique clairement ce que tu attendais comme résultat et ce qui s'est réellement passé. Inclue tous les messages d'erreur ou les tracebacks.

📜 Licence#

Ultralytics utilise la GNU Affero General Public License 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 que tous les utilisateurs ont la liberté d'utiliser, modifier et partager le logiciel, favorisant ainsi une forte communauté de collaboration et d'innovation.

Nous encourageons tous les contributeurs à se familiariser avec les conditions de la licence AGPL-3.0 pour contribuer efficacement et éthiquement à la communauté open-source 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 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é AGPL-3.0 est-elle importante ?#

Maintient le logiciel ouvert : Assure que les améliorations et les œ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 rendre ton projet open-source, envisage d'obtenir une licence entreprise.

Comment se conformer à l'AGPL-3.0#

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

Choisis ton point de départ :
- Fais un fork d'Ultralytics YOLO : Fais directement un fork du dépôt Ultralytics YOLO si tu construis ton projet de près en t'appuyant dessus.
- Utilise le modèle Ultralytics : Commence avec le dépôt de modèle Ultralytics pour une configuration propre et modulaire intégrant YOLO.
Licencie ton projet :
- Ajoute un fichier LICENSE contenant le texte intégral de la licence AGPL-3.0.
- Ajoute une notice en haut de chaque fichier source indiquant la licence.
Publie ton code source :
- Rends le code source de l'intégralité de ton projet accessible au public (par exemple, 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 Ultralytics YOLO.
  - Les scripts d'entraînement, de validation et d'inférence.
  - Les poids du modèle s'ils sont modifiés ou affinés (fine-tuned).
  - Les fichiers de configuration, configurations d'environnement (requirements.txt, Dockerfiles).
  - Le code backend et frontend s'il fait partie d'une application web.
  - Toutes bibliothèques tierces que tu as modifiées.
  - Les données d'entraînement si elles sont nécessaires pour exécuter/ré-entraîner et redistribuables.
Documente clairement :
- Met à 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.
- Mentionne Ultralytics YOLO de manière appropriée en faisant 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èle Ultralytics pour un exemple de structure 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 lignes directrices, tu assures la conformité avec l'AGPL-3.0, soutenant l'écosystème open-source qui permet des outils puissants comme Ultralytics YOLO.

Conclusion#

Merci pour ton intérêt à contribuer aux projets YOLO open-source d'Ultralytics. Ta participation est essentielle pour façonner l'avenir de notre logiciel et bâtir une communauté dynamique d'innovation et de collaboration. Que tu améliores du code, signales des bugs ou suggères de nouvelles fonctionnalités, tes contributions sont inestimables.

Nous sommes ravis 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 ce voyage passionnant de l'open-source.

FAQ#

Pourquoi devrais-je contribuer aux dépôts open-source 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 l'ensemble de la communauté. Les contributions peuvent inclure des améliorations de code, des corrections 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 et experts qualifiés du domaine, améliorant tes propres compétences et ta réputation. Pour plus de détails sur la façon de commencer, consulte la section Contribuer via des pull requests.

Comment signer le Contrat de Licence Contributeur (CLA) pour Ultralytics YOLO ?#

Pour signer le Contrat de Licence Contributeur (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 indiquant :

I have read the CLA Document and I sign the CLA

Pour plus d'informations, consulte la section Signature de la CLA.

Que sont 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. Lorsque tu contribues à Ultralytics YOLO, suivre les docstrings de style Google garantit que tes ajouts sont bien documentés et facilement compris. 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) GitHub Actions. Ces tests incluent le lissage (linting), les tests unitaires et d'autres vérifications pour garantir que le code répond aux normes de qualité du projet. Examine la sortie de la CI et corrige tout problème. Pour des informations détaillées sur le processus de CI et des conseils de dépannage, consulte la section Tests de CI GitHub Actions.

Comment puis-je signaler un bug dans les dépôts Ultralytics YOLO ?#

Pour signaler un bug, fournis un exemple minimum reproductible 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 minime tout en étant suffisant pour reproduire le problème. Pour des étapes plus détaillées sur la façon de signaler des bugs, consulte la section Signaler des 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'ensemble 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 à travers ses dérivés. Si tu ne peux pas respecter ces exigences, tu dois obtenir une licence entreprise. Consulte la section Rendre ton projet open-source pour plus de détails.

Contributeurs

GLglenn-jocher²⁴ RIRizwanMunawar³ RAraimbekovm¹ PDpderrenger¹ Y-Y-T-G¹ WIWillieMaddox¹ LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

Créé 12 nov. 2023Mis à jour il y a 3 semaines