Contribuer aux projets Open Source d'Ultralytics

Bienvenue ! Nous sommes ravis que vous envisagiez de contribuer à nos projets Ultralytics open-source. Votre implication contribue non seulement à améliorer la qualité de nos référentiels, mais profite également à l'ensemble de la communauté de la vision par ordinateur. Ce guide fournit des directives claires et les meilleures pratiques pour vous aider à démarrer.

Regarder : Comment contribuer au dépôt Ultralytics | Modèles, ensembles de données et documentation Ultralytics 🚀

🤝 Code de conduite

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

🚀 Contribuer via les demandes de tirage

Nous apprécions grandement les contributions sous forme de pull requests (PR). Pour que le processus d'examen se déroule le mieux possible, veuillez suivre les étapes suivantes :

1. Fork du référentiel : Commencez par forker le référentiel Ultralytics approprié (par exemple, ultralytics/ultralytics) sur votre compte GitHub.
2. Créer une branche : Créez une nouvelle branche dans votre dépôt dupliqué avec un nom clair et descriptif reflétant vos modifications (par exemple, fix-issue-123, add-feature-xyz).
3. Effectuer vos modifications : Mettez en œuvre vos améliorations ou correctifs. Assurez-vous que votre code respecte les consignes de style du projet et n’introduit pas de nouvelles erreurs ou de nouveaux avertissements.
4. Testez vos modifications : Avant de soumettre, testez vos modifications localement pour confirmer qu’elles fonctionnent comme prévu et n’entraînent pas de régressions. Ajoutez des tests si vous introduisez de nouvelles fonctionnalités.
5. Validez vos modifications : Validez vos modifications avec des messages de commit concis et descriptifs. Si vos modifications concernent un problème spécifique, incluez le numéro du problème (par exemple, Fix #123: Corrected calculation error.).
6. Créer une demande de tirage : Soumettez une "pull request" depuis votre branche vers le main branche du référentiel Ultralytics original. Fournissez un titre clair et une description détaillée expliquant le but et la portée de vos modifications.

📝 Signature de l'accord de licence du contributeur (CLA)

Avant que nous puissions fusionner votre requête d'extraction, vous devez signer notre Contrat de Licence de Contributeur (CLA). Cet accord juridique garantit que vos contributions sont correctement concédées sous licence, ce qui permet au projet de continuer à être distribué sous la licence AGPL-3.0.

Après avoir soumis votre requête d'extraction, le robot CLA vous guidera dans le processus de signature. Pour signer le CLA, ajoutez simplement un commentaire dans votre PR indiquant :

I have read the CLA Document and I sign the CLA

✍️ Chaînes de documentation de style Google

Lors de l'ajout de nouvelles fonctions ou classes, inclure Chaînes de documentation de style Google pour une documentation claire et standardisée. Encadrez toujours les entrées et les sorties types 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

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

✅ Tests CI GitHub Actions

Toutes les demandes dePull doivent passer les tests d'Actions GitHub d'Intégration Continue (CI) avant de pouvoir être fusionnées. Ces tests comprennent le linting, les tests unitaires et d'autres vérifications pour s'assurer que vos modifications répondent aux normes de qualité du projet. Examinez la sortie de CI et corrigez les problèmes qui surviennent.

✨ Bonnes pratiques pour les contributions de code

Lorsque vous contribuez du code aux projets Ultralytics, gardez ces bonnes pratiques à l'esprit :

• Éviter la duplication de code : Réutiliser le code existant autant que possible et minimiser les arguments inutiles.
• Effectuer des modifications plus petites et ciblées : Concentrez-vous sur des modifications ciblées plutôt que sur des changements à grande échelle.
• Simplifier autant que possible : Recherchez les possibilités de simplifier le code ou de supprimer les parties inutiles.
• Tenir compte de la compatibilité : Avant d'effectuer des modifications, déterminez si elles pourraient casser le code existant utilisant Ultralytics.
• Utiliser une mise en forme cohérente : Des outils tels que Ruff Formatter peuvent aider à maintenir une cohérence stylistique.
• Ajouter des tests appropriés : Inclure des tests pour les nouvelles fonctionnalités afin de s'assurer qu'elles fonctionnent comme prévu.

👀 Examen des demandes de tirage

L'examen des demandes de tirage est une autre façon précieuse de contribuer. Lors de l'examen des PR :

• Vérifier les tests unitaires : Vérifiez que la PR inclut des tests pour les nouvelles fonctionnalités ou modifications.
• Vérifier les mises à jour de la documentation : S’assurer que la documentation est mise à jour pour refléter les changements.
• Évaluer l'impact sur les performances : Déterminez comment les changements pourraient affecter les performances.
• Vérifier les tests CI : Confirmer que tous les tests d'intégration continue sont réussis.
• Fournir une rétroaction constructive: Offrez une rétroaction spécifique et claire sur tout problème ou préoccupation.
• Reconnaître les efforts : Reconnaître le travail de l'auteur pour maintenir une atmosphère de collaboration positive.

🐞 Signalement de bugs

Nous accordons une grande importance aux rapports de bogues, car ils nous aident à améliorer la qualité et la fiabilité de nos projets. Lorsque vous signalez un bogue via GitHub Issues :

• Vérifier les problèmes existants : Effectuez d'abord une recherche pour voir si le bug a déjà été signalé.
• Fournir un exemple minimal reproductible: Créez un petit extrait de code autonome qui reproduit systématiquement le problème. Ceci est crucial pour un débogage efficace.
• Décrivez l'environnement : Spécifiez votre système d'exploitation, votre version de Python, les versions des bibliothèques concernées (par exemple, torch, ultralytics), et le matériel (CPU/GPU).
• Expliquer le comportement attendu par rapport au comportement réel : Indiquez clairement ce que vous vous attendiez à ce qu'il se passe et ce qui s'est réellement passé. Incluez tous les messages d'erreur ou les traces de pile.

📜 Licence

Ultralytics utilise la GNU Affero General Public License v3.0 (AGPL-3.0) pour ses référentiels. Cette licence favorise l'ouverture, la transparence et l'amélioration collaborative dans le développement de logiciels. Elle garantit que tous les utilisateurs ont la liberté d'utiliser, de modifier et de partager le logiciel, favorisant ainsi une forte 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 efficacement et de manière éthique à la communauté open source Ultralytics.

🌍 Ouvrir votre projet YOLO en Open Source sous AGPL-3.0

Vous utilisez des modèles ou du code Ultralytics YOLO dans votre projet ? La licence AGPL-3.0 exige que l'ensemble de votre œuvre dérivée soit également open source sous AGPL-3.0. Cela garantit que les modifications et les projets plus importants construits sur des bases open source restent ouverts.

Pourquoi la conformité AGPL-3.0 est-elle importante ?

• Garantit l'ouverture des logiciels : Garantit que les améliorations et les travaux dérivés profitent à la communauté.
• Exigence légale : L’utilisation de code sous licence AGPL-3.0 lie votre projet à ses conditions.
• Favorise la collaboration : Encourage le partage et la transparence.

Si vous préférez ne pas rendre votre projet open source, envisagez d'obtenir une licence d'entreprise.

Comment se conformer à la licence AGPL-3.0

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

1. Choisissez votre point de départ :

   • Forkez Ultralytics YOLO : Forkez directement le dépôt Ultralytics YOLO si vous construisez étroitement dessus.
   • Utiliser le modèle Ultralytics : Commencez avec le référentiel de modèles Ultralytics pour une configuration propre et modulaire intégrant YOLO.

2. Licenciez votre projet :

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

3. Publier votre code source :

   • Créez votre code source de l'ensemble du projet publiquement accessible (par exemple, sur GitHub). Cela comprend :
     • L'application ou le système complet et de plus grande envergure qui intègre le modèle ou le code YOLO.
     • Toute modification apportée au code Ultralytics YOLO original.
     • Scripts pour l'entraînement, la validation, l'inférence.
     • Poids du modèle si modifiés ou affinés.
     • Fichiers de configuration, les configurations d'environnement (requirements.txt, Dockerfiles).
     • Code backend et frontend s'il fait partie d'une application web.
     • Toute bibliothèque tierce que vous avez modifiée.
     • Données d'entraînement si nécessaire pour exécuter/réentraîner et redistribuable.

4. Documentez clairement :

   • Mettez à jour votre README.md pour indiquer que le projet est sous licence AGPL-3.0.
   • Inclure des instructions claires sur la façon de configurer, de construire et d'exécuter votre projet à partir du code source.
   • Attribuer Ultralytics YOLO de manière appropriée, en renvoyant 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

Consultez le dépôt de modèles 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 directives, vous vous assurez de la conformité avec AGPL-3.0, soutenant ainsi l'écosystème open source qui permet des outils puissants comme Ultralytics YOLO.

🎉 Conclusion

Nous vous remercions de votre intérêt à contribuer aux projets Ultralytics open source YOLO. Votre participation est essentielle pour façonner l'avenir de notre logiciel et construire une communauté dynamique d'innovation et de collaboration. Que vous amélioriez le code, signaliez des bogues ou suggériez de nouvelles fonctionnalités, vos contributions sont inestimables.

Nous sommes ravis de voir vos idées prendre vie et apprécions votre engagement à faire progresser la technologie de détection d'objets. Ensemble, continuons à croître et à innover dans ce passionnant parcours open source. Bon codage ! 🚀🌟

FAQ

Pourquoi devrais-je contribuer aux référentiels open source Ultralytics YOLO ?

Contribuer aux référentiels open source 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 la documentation et de nouvelles implémentations de fonctionnalités. De plus, contribuer vous permet de collaborer avec d'autres développeurs et experts qualifiés dans le domaine, améliorant ainsi vos propres compétences et votre réputation. Pour plus de détails sur la façon de commencer, consultez la section Contribuer via les demandes de tirage.

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

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

I have read the CLA Document and I sign the CLA

Pour plus d'informations, consultez la section Signature CLA.

Que sont les docstrings de style Google et pourquoi sont-elles requises pour les contributions à Ultralytics YOLO ?

Les chaînes de documentation de style Google fournissent une documentation claire et concise pour les fonctions et les classes, améliorant ainsi la lisibilité et la maintenabilité du code. Ces chaînes de documentation décrivent le but, les arguments et les valeurs de retour de la fonction avec des règles de formatage spécifiques. Lorsque vous contribuez à Ultralytics YOLO, le respect des chaînes de documentation de style Google garantit que vos ajouts sont bien documentés et facilement compris. Pour des exemples et des directives, consultez la section Chaînes de documentation de style Google.

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

Avant que votre requête d'extraction puisse être fusionnée, elle doit passer tous les tests d'intégration continue (CI) de GitHub Actions. Ces tests comprennent le linting, les tests unitaires et d'autres vérifications pour s'assurer que le code répond aux normes de qualité du projet. Examinez la sortie de CI et corrigez tout problème. Pour des informations détaillées sur le processus de CI et des conseils de dépannage, consultez la section Tests CI de GitHub Actions.

Comment signaler un bug dans les référentiels Ultralytics YOLO ?

Pour signaler un bug, fournissez un exemple minimal reproductible clair et concis avec votre rapport de bug. Cela aide les développeurs à identifier et à corriger rapidement le problème. Assurez-vous que votre exemple est minimal, mais suffisant pour reproduire le problème. Pour des étapes plus détaillées sur le signalement des bugs, consultez la section Signalement des bugs.

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

Si vous utilisez du code ou des modèles Ultralytics YOLO (sous licence AGPL-3.0) dans votre projet, la licence AGPL-3.0 exige que l'ensemble de votre projet (l'œuvre dérivée) soit également sous licence AGPL-3.0 et que son code source complet soit mis à disposition du public. Cela garantit que la nature open source du logiciel est préservée dans tous ses dérivés. Si vous ne pouvez pas satisfaire à ces exigences, vous devez obtenir une licence d'entreprise. Consultez la section Open-Sourcing Your Project pour plus de détails.

📅 Créé il y a 1 an ✏️ Mis à jour il y a 2 mois

Commentaires