Contribuer aux projets Open-Source Ultralytics

Bienvenue ! Nous sommes ravis que vous envisagiez de contribuer à notre projet Ultralytics à nos projets open-source Ultralytics. Votre implication ne contribue pas 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 des bonnes pratiques pour vous aider à démarrer.

Regarder : Comment contribuer au référentiel Ultralytics | Modèles, jeux de données et documentation Ultralytics 🚀

🤝 Code de conduite

Afin de garantir un environnement accueillant et inclusif pour tous, tous les contributeurs doivent adhérer à notre code de conduite. Le respect, la gentillesse et le professionnalisme sont au cœur de notre communauté.

🚀 Contribuer via les Pull Requests

Nous apprécions grandement les contributions sous forme de demandes de téléchargement (PR). Pour que le processus de révision soit le plus fluide possible, veuillez suivre les étapes suivantes :

1. Forger le dépôt: Commencez par forker le dépôt Ultralytics concerné (par exemple, ultralytics) sur votre compte GitHub.
2. Créer une branche: Créez une nouvelle branche dans votre dépôt forké avec un nom clair et descriptif reflétant vos changements (par exemple, fix-issue-123, add-feature-xyz).
3. Effectuez vos changements : Mettez en œuvre vos améliorations ou vos corrections. Assurez-vous que votre code respecte les règles de style du projet et qu'il n'introduit pas de nouvelles erreurs ou de nouveaux avertissements.
4. Testez vos modifications : Avant de soumettre vos modifications, testez-les localement pour vous assurer qu'elles fonctionnent comme prévu et qu'elles n'entraînent pas de régressions. Ajoutez des tests si vous introduisez de nouvelles fonctionnalités.
5. Validez vos modifications: Livrez vos modifications à l'aide de messages de livraison concis et descriptifs. Si vos modifications concernent un problème spécifique, indiquez le numéro du problème (par exemple, Fix #123: Corrected calculation error.).
6. Créer une demande d'extraction: Soumettre une demande d'extraction (pull request) de votre branche à la base de données main du dépôt original Ultralytics . Fournissez un titre clair et une description détaillée expliquant l'objectif et la portée de vos modifications.

📝 Signature de la CCT

Avant que nous puissions fusionner votre demande d'extraction, vous devez signer notre Accord de licence du contributeur (CLA). Cet accord juridique garantit que vos contributions sont correctement licenciées, ce qui permet au projet de continuer à être distribué sous la licenceAGPL-3.0

Après avoir soumis votre demande d'extraction, le robot CLA vous guidera tout au long du processus de signature. Pour signer la CLA, il suffit d'ajouter un commentaire dans votre PR indiquant :

I have read the CLA Document and I sign the CLA

✍️ Docstrings de Google

Lorsque vous ajoutez de nouvelles fonctions ou classes, incluez Chaînes de documents Google pour une documentation claire et normalisée. Toujours joindre les données d'entrée et de sortie 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

✅ GitHub Actions CI Tests

Toutes les demandes d'extraction doivent passer les tests d'intégration continue (CI) des actions GitHub avant d'être fusionnées. Ces tests comprennent le linting, les tests unitaires et d'autres vérifications pour s'assurer que vos changements respectent les normes de qualité du projet. Examinez les résultats de l'intégration continue et résolvez les problèmes éventuels.

✨ Bonnes pratiques pour les contributions au code

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

• Éviter la duplication du code : Réutiliser le code existant dans la mesure du possible et minimiser les arguments inutiles.
• Apporter des changements plus petits et plus ciblés : Concentrez-vous sur des modifications ciblées plutôt que sur des changements à grande échelle.
• Simplifier lorsque c'est possible : Cherchez à simplifier le code ou à supprimer les parties inutiles.
• Tenir compte de la compatibilité : Avant d'apporter des changements, il faut se demander s'ils ne risquent pas de perturber le code existant qui utilise Ultralytics.
• Utilisez un formatage cohérent : Des outils comme Ruff Formatter peuvent aider à maintenir une cohérence stylistique.
• Ajouter les tests appropriés : Inclure des tests pour les nouvelles fonctionnalités afin de s'assurer qu'elles fonctionnent comme prévu.

👀 Revue des Pull Requests

La révision des demandes d'extraction est une autre façon de contribuer. Lors de la révision des PR :

• Vérifier la présence de tests unitaires : Vérifier que le PR inclut des tests pour les nouvelles fonctionnalités ou les changements.
• Examiner 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 : Examinez comment les changements peuvent affecter les performances.
• Vérifier les tests d'intégration continue : Confirmer que tous les tests d'intégration continue sont réussis.
• Fournir un retour d'information constructif : Offrez un retour d'information spécifique et clair sur tout problème ou préoccupation.
• Reconnaître les efforts : Reconnaître le travail de l'auteur afin de maintenir une atmosphère de collaboration positive.

🐞 Signaler des bogues

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 : Recherchez d'abord si le bogue a déjà été signalé.
• Fournir un exemple minimum reproductible: Créez un petit extrait de code autonome qui reproduit le problème de manière cohérente. C'est essentiel pour un débogage efficace.
• Décrire l'environnement : Spécifiez votre système d'exploitation, la version de Python , les versions des bibliothèques concernées (par exemple, torch, ultralytics), et le matériel (CPU/GPU).
• Expliquez le comportement attendu par rapport au comportement réel : Indiquez clairement ce que vous attendiez et ce qui s'est réellement produit. Inclure tout message d'erreur ou toute trace.

📜 Licence

Ultralytics utilise la licence publique générale GNU Affero 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 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 licenceAGPL-3.0 afin de contribuer efficacement et éthiquement à la communauté open-source Ultralytics .

🌍 L'Open-Sourcing de votre projet YOLO sous AGPL-3.0

Vous utilisez les modèles ou le codeYOLO d'Ultralytics dans votre projet ? La licenceAGPL-3.0 exige que l'ensemble de votre travail dérivé soit également ouvert sous AGPL-3.0 Cela permet de garantir que les modifications et les projets plus importants construits sur la base de logiciels libres restent ouverts.

L'importance de la conformité à l'AGPL-3.0

• Maintient le logiciel ouvert : Veille à ce que les améliorations et les travaux dérivés profitent à la communauté.
• Exigence légale : L'utilisation d'un 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 mettre votre projet en open-source, envisagez d'obtenir une licence d'entreprise.

Comment se conformer à l'AGPL-3.0

Se conformer signifie mettre le code source complet de votre projet à la disposition du public sous la licence AGPL-3.0

1. Choisissez votre point de départ :

   • Fork Ultralytics YOLO: Forker directement le dépôtUltralytics YOLO si l'on s'en inspire étroitement.
   • Utiliser le modèle Ultralytics : Commencez par le référentiel de modèlesUltralytics pour une installation propre et modulaire intégrant YOLO.

2. Licence de votre projet :

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

3. Publiez votre code source :

   • Faites votre l'ensemble du code source du projet accessibles au public (par exemple, sur GitHub). Il s'agit notamment de
     • L'application ou le système complet de plus grande envergure qui intègre le modèle ou le code YOLO .
     • Toute modification apportée au code original d'Ultralytics YOLO .
     • Scripts pour l'entraînement, la validation et l'inférence.
     • Poids du modèle en cas de modification ou d'ajustement.
     • Fichiers de configuration, les configurations de l'environnement (requirements.txt, Dockerfiles).
     • Le code du backend et du frontend s'il fait partie d'une application web.
     • Toutes les bibliothèques tierces que vous avez modifiées.
     • Données d'entraînement si elles sont nécessaires pour l'exécution/le réentraînement et redistribuables.

4. Document clair :

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

Reportez-vous au référentiel de modèlesUltralytics pour un exemple pratique 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 directives, vous garantissez la conformité avec l'AGPL-3.0, en soutenant l'écosystème open-source qui permet d'utiliser des outils puissants comme Ultralytics YOLO.

🎉 Conclusion

Nous vous remercions de l'intérêt que vous portez à la contribution aux Ultralytics aux projets 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. Qu'il s'agisse d'améliorer le code, de signaler des bogues ou de suggérer de nouvelles fonctionnalités, votre contribution est inestimable.

Nous sommes ravis de voir vos idées se concrétiser et nous apprécions votre engagement à faire progresser la technologie de détection d'objets. Ensemble, continuons à nous développer et à innover dans le cadre de cette passionnante aventure open-source. Bon codage ! 🚀🌟

FAQ

Pourquoi devrais-je contribuer aux dépôts de logiciels libres de Ultralytics YOLO ?

Contribuer aux dépôts de code source libre de Ultralytics YOLO permet d'améliorer le logiciel, de le rendre plus robuste et plus riche en fonctionnalités pour l'ensemble de la communauté. Les contributions peuvent inclure des améliorations du code, des corrections de bogues, des améliorations de la documentation et la mise en œuvre de nouvelles fonctionnalités. En outre, les contributions vous permettent de collaborer avec d'autres développeurs compétents et des experts dans le domaine, ce qui améliore vos propres compétences et votre réputation. Pour plus d'informations sur la manière de commencer, reportez-vous à la section Contribuer par le biais de demandes d'extraction (Pull Requests).

Comment signer l'accord de licence du contributeur (CLA) pour Ultralytics YOLO ?

Pour signer l'accord de licence du contributeur (CLA), suivez les instructions fournies par le robot CLA après avoir soumis votre demande d'extraction. Ce processus permet de s'assurer que vos contributions sont correctement placées sous la licence AGPL-3.0 , ce qui préserve l'intégrité juridique du projet open-source. Ajoutez un commentaire dans votre demande d'extraction indiquant :

I have read the CLA Document and I sign the CLA

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

Que sont les chaînes de documents de type Google et pourquoi sont-elles nécessaires pour les contributions Ultralytics YOLO ?

Google-fournissent une documentation claire et concise pour les fonctions et les classes, améliorant ainsi la lisibilité et la maintenabilité du code. Elles décrivent l'objectif de la fonction, ses arguments et ses valeurs de retour en respectant des règles de formatage spécifiques. Lorsque vous contribuez à Ultralytics YOLO , le fait de suivre les docstrings de style Google garantit que vos ajouts sont bien documentés et facilement compréhensibles. Pour des exemples et des lignes directrices, consultez la section Google-Style Docstrings.

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

Avant que votre demande ne soit fusionnée, elle doit passer tous les tests d'intégration continue (CI) des actions GitHub. 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 les résultats de l'intégration continue et corrigez les problèmes éventuels. Pour obtenir des informations détaillées sur le processus d'intégration continue et des conseils de dépannage, consultez la section Tests d'intégration continue des Actions GitHub.

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

Pour signaler un bogue, fournissez un exemple minimum reproductible clair et concis avec votre rapport de bogue. Cela permet aux développeurs d'identifier et de résoudre rapidement le problème. Veillez à ce que votre exemple soit minimal mais suffisant pour reproduire le problème. Pour plus de détails sur les étapes à suivre pour signaler des bogues, consultez la section Signaler des bogues.

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

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

📅C réé il y a 1 an ✏️ Mis à jour il y a 1 mois

Commentaires