Contribution au noyau sémantique

Vous pouvez contribuer au noyau sémantique en envoyant des problèmes, en démarrant des discussions et en envoyant des demandes de tirage (PRS). La contribution du code est grandement appréciée, mais le simple fait de déposer des problèmes pour les problèmes que vous rencontrez est également un excellent moyen de contribuer, car il nous aide à concentrer nos efforts.

Problèmes liés à la création de rapports et commentaires

Nous accueillons toujours les rapports de bogues, les propositions d’API et les commentaires globaux. Étant donné que nous utilisons GitHub, vous pouvez utiliser les onglets Problèmes et Discussions pour démarrer une conversation avec l’équipe. Vous trouverez ci-dessous quelques conseils lors de l’envoi de problèmes et de commentaires afin que nous puissions répondre à vos commentaires le plus rapidement possible.

Signaler un problème

De nouveaux problèmes pour le Kit de développement logiciel (SDK) peuvent être signalés dans notre liste de problèmes, mais avant de déposer un nouveau problème, recherchez la liste des problèmes pour vous assurer qu’il n’existe pas déjà. Si vous rencontrez des problèmes avec la documentation du noyau sémantique (ce site), envoyez un problème dans le référentiel de documentation du noyau sémantique.

Si vous trouvez un problème existant pour ce que vous souhaitez signaler, veuillez inclure vos propres commentaires dans la discussion. Nous vous recommandons également de voter (👍 réaction) le billet d’origine, car cela nous aide à hiérarchiser les problèmes populaires dans notre backlog.

Écriture d’un bon rapport de bogues

De bons rapports de bogues facilitent la vérification et la cause racine du problème sous-jacent. Mieux un rapport de bogues est amélioré, plus le problème peut être résolu plus rapidement. Dans l’idéal, un rapport de bogues doit contenir les informations suivantes :

• Description générale du problème.
• Une reproduction minimale, c’est-à-dire la plus petite taille de code/configuration requise pour reproduire le comportement incorrect.
• Description du comportement attendu, contrairement au comportement réel observé.
• Informations sur l’environnement : système d’exploitation/distribution, architecture du processeur, version du SDK, etc.
• Des informations supplémentaires, par exemple, sont-elles une régression des versions précédentes ? Existe-t-il des solutions de contournement connues ?

Envoi de commentaires

Si vous avez des commentaires généraux sur le noyau sémantique ou les idées sur la façon de l’améliorer, veuillez le partager sur notre tableau de discussion. Avant de commencer une nouvelle discussion, recherchez la liste des discussions pour vous assurer qu’elle n’existe pas déjà.

Nous vous recommandons d’utiliser la catégorie idées si vous avez une idée spécifique que vous souhaitez partager et la catégorie Q&A si vous avez une question sur le noyau sémantique.

Vous pouvez également démarrer des discussions (et partager tous les commentaires que vous avez créés) dans la communauté Discord en rejoignant le serveur Discord du noyau sémantique.

Aidez-nous à hiérarchiser les commentaires

Nous utilisons actuellement des votes pour nous aider à hiérarchiser les problèmes et les fonctionnalités de notre backlog. Par conséquent, nous vous conseillons de voter à tous les problèmes ou discussions que vous souhaitez voir abordés.

Si vous pensez que d’autres tirent parti d’une fonctionnalité, nous vous encourageons également à demander à d’autres personnes de voter à la question. Cela nous aide à hiérarchiser les problèmes qui affectent le plus d’utilisateurs. Vous pouvez demander à vos collègues, amis ou à la communauté sur Discord de voter un problème en partageant le lien vers le problème ou la discussion.

Envoi de demandes de tirage

Nous accueillons les contributions au noyau sémantique. Si vous avez un correctif de bogue ou une nouvelle fonctionnalité que vous souhaitez contribuer, suivez les étapes ci-dessous pour envoyer une demande de tirage (PULL). Ensuite, les maintenances de projet passent en revue les modifications du code et les fusionnent une fois qu’ils ont été acceptés.

Flux de travail de contribution recommandé

Nous vous recommandons d’utiliser le flux de travail suivant pour contribuer au noyau sémantique (il s’agit du même flux de travail que celui utilisé par l’équipe du noyau sémantique) :

1. Créez un problème pour votre travail.
   • Vous pouvez ignorer cette étape pour les modifications triviales.
   • Réutilisez un problème existant sur la rubrique, s’il en existe un.
   • Obtenez l’accord de l’équipe et de la communauté que votre changement proposé est un bon en utilisant la discussion dans la question.
   • Indiquez clairement dans le problème que vous allez prendre en charge l’implémentation. Cela nous permet d’affecter le problème à vous et de s’assurer que quelqu’un d’autre ne fonctionne pas accidentellement dessus.
2. Créez une duplication personnelle du référentiel sur GitHub (si vous n’en avez pas déjà).
3. Dans votre fourche, créez une branche hors main (git checkout -b mybranch).
   • Nommez la branche afin qu’elle communique clairement vos intentions, telles que « issue-123 » ou « githubhandle-issue ».
4. Apportez et validez vos modifications dans votre branche.
5. Ajoutez de nouveaux tests correspondant à votre modification, le cas échéant.
6. Générez le référentiel avec vos modifications.
   • Assurez-vous que les builds sont propres.
   • Assurez-vous que les tests passent tous, y compris vos nouveaux tests.
7. Créez une demande de tirage sur la branche principale du référentiel.
   • État dans la description du problème ou de l’amélioration que votre modification traite.
   • Vérifiez que toutes les vérifications d’intégration continue sont passées.
8. Attendez les commentaires ou l’approbation de vos modifications des responsables de la maintenance du code.
9. Lorsque les propriétaires de zone se sont connectés et que toutes les vérifications sont vertes, votre demande de tirage sera fusionnée.

Dos and Don’ts lors de la contribution

Voici une liste de tâches et de non que nous vous recommandons lors de la contribution au noyau sémantique pour nous aider à passer en revue et fusionner vos modifications le plus rapidement possible.

Procédez comme suit :

• Suivez le style de codage .NET standard et le style de code Python
• Donnez la priorité au style actuel du projet ou du fichier que vous modifiez s’il diffère des instructions générales.
• Incluez des tests lors de l’ajout de nouvelles fonctionnalités. Lors de la résolution des bogues, commencez par ajouter un test qui met en évidence la façon dont le comportement actuel est rompu.
• Gardez les discussions ciblées. Lorsqu’un sujet nouveau ou associé apparaît, il est souvent préférable de créer un problème que de suivre la discussion.
• Faites clairement état d’un problème que vous allez prendre en compte pour l’implémenter.
• Blog et/ou tweet sur vos contributions !

N’oubliez pas :

• Ne surprisez pas l’équipe avec des demandes de tirage volumineuses. Nous voulons soutenir les contributeurs, donc nous vous recommandons de déposer un problème et de commencer une discussion afin que nous puissions nous entendre sur une direction avant d’investir beaucoup de temps.
• Ne validez pas le code que vous n’avez pas écrit. Si vous trouvez du code que vous pensez être adapté à l’ajout au noyau sémantique, déposez un problème et démarrez une discussion avant de continuer.
• N’envoyez pas de demandes de tirage qui modifient les fichiers ou en-têtes associés aux licences. Si vous pensez qu’il y a un problème avec eux, déposez un problème et nous serons heureux de le discuter.
• Ne faites pas de nouvelles API sans déposer un problème et discuter avec l’équipe en premier. L’ajout d’une nouvelle surface publique à une bibliothèque est une affaire importante et nous voulons nous assurer que nous avons bien accès.

Dernières modifications

Les contributions doivent maintenir la signature de l’API et la compatibilité comportementale. Si vous souhaitez apporter une modification qui interrompt le code existant, envoyez un problème pour discuter de votre idée ou modifier si vous pensez qu’une modification cassant est justifiée. Sinon, les contributions qui incluent des changements cassants seront rejetées.

Processus d’intégration continue (CI)

Le système d’intégration continue (CI) effectue automatiquement les builds requises et exécute les tests (y compris ceux que vous devez également exécuter localement) pour les demandes de tirage. Les builds et les exécutions de test doivent être propres avant qu’une demande de tirage puisse être fusionnée.

Si la build CI échoue pour une raison quelconque, le problème de demande de tirage est mis à jour avec un lien qui peut être utilisé pour déterminer la cause de l’échec afin qu’il puisse être résolu.

Contribution à la documentation

Nous acceptons également les contributions au référentiel de documentation du noyau sémantique.