Contribuer aux référentiels de documentation .NET

Nous vous remercions de l’intérêt que vous portez à la documentation .NET à travers vos contributions.

Ce document explique comment contribuer aux articles et aux exemples de code hébergés sur le site de documentation .NET. Les contributions peuvent aller de la simple correction de fautes de frappe à la rédaction complexe de nouveaux articles.

Le site de documentation .NET repose sur plusieurs référentiels. En voici une liste non-exhaustive :

• Articles conceptuels et extraits de code .NET
• Exemples et extraits de code
• Informations de référence sur l’API .NET
• Informations de référence sur le kit SDK .NET Compiler Platform
• Informations de référence sur l'API ML.NET

Conseils relatifs aux contributions

Nous apprécions toute contribution de la communauté à la documentation. Vous trouverez ci-dessous quelques règles qu’il convient de garder à l’esprit quand vous contribuez à la documentation .NET :

• À ne pas faire : Nous surprendre avec des demandes de tirage démesurées. Soumettez plutôt un problème et démarrez une discussion pour convenir avec nous de la direction à prendre avant d’investir beaucoup de votre temps.
• N’incluez pas d’exemple de code inline dans un article.
• Utilisez un projet d’extrait de code avec du code à incorporer dans l’article.
• Suivez ces instructions et respectez le guide de style.
• À faire : Utiliser le fichier de modèle comme point de départ de votre travail.
• À faire : Créer une branche distincte dans votre duplication (fork) avant de travailler sur les articles.
• Suivez le flux GitHub.
• Rédigez des tweets et des billets de blog (ou autres) concernant vos contributions.

Le respect de ces instructions est garant d’une meilleure expérience à la fois pour vous et pour nous.

Processus de contribution

Étape 1 : Si vous souhaitez écrire un nouveau contenu ou examiner en détail un contenu existant, ouvrez un problème en décrivant ce que vous voulez faire. Le contenu situé dans le dossier docs est organisé en sections que l’on retrouve dans la table des matières. Définissez l’emplacement de la rubrique dans la table des matières. Obtenez des commentaires sur votre proposition.

-ou-

Choisissez un problème existant et résolvez-le. Vous pouvez consulter notre liste de problèmes ouverts et vous porter volontaire pour travailler sur ceux qui vous intéressent :

• Filtrez les problèmes à l’aide de l’étiquette good first issue pour afficher les problèmes auxquels les débutants peuvent s’attaquer en premier.
• Filtrez les problèmes à l’aide de l’étiquette help wanted pour afficher les problèmes adaptés à une contribution de la communauté. Ces problèmes nécessitent généralement un contexte minimal.
• Les contributeurs expérimentés peuvent résoudre n’importe quel problème qui les intéresse.

Quand vous avez trouvé un problème à résoudre, ajoutez un commentaire pour demander s’il est ouvert.

Une fois que vous avez choisi une tâche à exécuter, créez un compte GitHub et passez à l’étape 2.

Étape 2 : Dupliquez (fork) le /dotnet/docs référentiel (ou le référentiel auquel vous contribuez) selon vos besoins et créez une branche pour vos modifications.

Pour les petites modifications, consultez Modifier dans le navigateur.

Étape 3 : appliquez les modifications sur cette nouvelle branche.

S’il s’agit d’une nouvelle rubrique, vous pouvez utiliser ce fichier de modèle comme point de départ. Il contient les recommandations rédactionnelles et explique aussi les métadonnées nécessaires pour chaque article, comme les informations sur l’auteur. Pour plus d’informations sur la syntaxe Markdown qui est utilisée dans Microsoft Learn, consultez Informations de référence sur Markdown.

Accédez au dossier qui correspond à l’emplacement de la table des matières de votre article déterminé dans l’Étape 1. Ce dossier contient les fichiers Markdown de tous les articles de la section. Si nécessaire, créez un nouveau dossier pour y placer les fichiers de votre contenu. Le principal article de cette section s’appelle index.md.

Pour les images et d’autres ressources statiques, créez un sous-dossier appelé media dans le dossier contenant votre article, s’il n’existe pas déjà. Dans le dossier media, créez un sous-dossier portant le nom de l’article (sauf pour le fichier index). Pour plus d’informations sur l’emplacement de vos fichiers, consultez la section Exemple de structure de dossiers.

N’incluez pas de code inline dans l’article, sauf si vous illustrez une construction qui ne se compile pas. Utilisez plutôt un projet d’extraits de code et incluez le code à l’aide de l’extension de code. Cela garantit que votre exemple de code est validé par notre système CI.

Pour les extraits de code, créez un sous-dossier nommé snippets dans le dossier qui contient votre article, s’il n’existe pas déjà. Dans le dossier snippets, créez un sous-dossier portant le nom de l’article. Dans la plupart des cas, vous disposez d’extraits de code pour les trois principaux langages .NET : C#, F# et Visual Basic. Par conséquent, créez des sous-dossiers appelés csharp, fsharp et vb pour chacun des trois projets. Si vous créez un extrait de code pour un article dans les dossiers docs/csharp, docs/fsharp ou docs/visual-basic, l’extrait de code ne sera utilisé que dans un seul langage, ce qui vous permet d’omettre le sous-dossier du langage. Pour plus d’informations sur l’emplacement de vos fichiers, consultez la section Exemple de structure de dossiers.

Les extraits de code sont de petits exemples de code ciblés qui illustrent les concepts abordés dans un article. Les programmes plus volumineux, destinés au téléchargement et à l’exploration, doivent se trouver dans le dépôt dotnet/samples. Les exemples complets sont traités dans la section dans Contribution aux exemples de code.

Étape 4 : Envoyez une demande de tirage (PR, Pull Request) de votre branche à la branche par défaut.

Chaque demande de tirage (pull request) doit généralement traiter un seul problème à la fois, sauf si plusieurs problèmes sont liés au même correctif de demande de tirage. La demande de tirage peut modifier un ou plusieurs fichiers. Si vous gérez plusieurs correctifs sur des fichiers différents, il est préférable d’utiliser des demandes de tirage distinctes.

Si votre demande de tirage résout un problème existant, ajoutez le mot clé Fixes #Issue_Number à la description de la demande de tirage. De cette façon, le problème est automatiquement fermé lorsque la demande de tirage est fusionnée. Pour plus d’informations, consultez Linking a pull request to an issue using a keyword.

L’équipe .NET examine votre demande de tirage et vous fait savoir si d’autres mises à jour/modifications sont nécessaires à son approbation.

Étape 5 : Mettez à jour votre branche comme l’équipe vous l’y a invité.

Les personnes chargées de la maintenance fusionneront votre demande de tirage dans la branche par défaut une fois que les commentaires auront été appliqués et que vos changements auront été approuvés.

Nous envoyons (push) régulièrement toutes les validations de la branche par défaut à la branche active ; vous pourrez alors voir votre contribution dans la documentation .NET. En règle générale, nous effectuons des publications chaque jour ouvré.

Exemple de structure de dossiers

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

La structure montrée ci-dessus comprend une image, portability_report.png et trois projets de code qui contiennent des extraits de code, eux-mêmes inclus dans l’article porting-overview.md.

Le dossier snippets/shared est utilisé pour les extraits de code qui peuvent s’étendre sur plusieurs articles d’un même dossier parent, tel que le dossier porting de l’exemple précédent. Utilisez le dossier shared uniquement lorsque vous avez une raison particulière de le faire, par exemple si vous avez du code XAML référencé par plusieurs articles, mais que vous ne pouvez pas compiler dans le dossier article-specific.

Les éléments multimédias peuvent également être partagés entre plusieurs articles lorsque ceux-ci se trouvent dans le même dossier parent, tel que le dossier porting de l’exemple précédent. Vous devez éviter autant que possible d’utiliser le dossier shared, et l’utiliser uniquement lorsque cela s’avère pertinent. Par exemple, il peut être judicieux de partager l’écran de chargement d’une application lorsque vous en faites une démonstration, ou de partager des boîtes de dialogue Visual Studio qui sont réutilisées dans plusieurs articles.

Contribuer aux exemples

Nous faisons la distinction suivante pour le code qui prend en charge notre contenu :

• Exemples : les lecteurs peuvent télécharger et exécuter les échantillons. Tous les échantillons doivent représenter des applications ou des bibliothèques complètes. Lorsque l’échantillon crée une bibliothèque, il doit inclure des tests unitaires ou une application permettant aux lecteurs d’exécuter le code. Ils utilisent souvent plusieurs technologies, fonctionnalités ou boîtes à outils. Le fichier readme.md de chaque exemple de code fera référence à l’article afin que vous puissiez en savoir davantage sur les concepts traités dans chaque exemple.
• Extraits de code : illustre un concept ou une tâche de moindre importance. Ils compilent mais ne sont pas destinés à être des applications complètes. Ils doivent s’exécuter correctement, mais ne constituent pas un exemple d’application pour un scénario type. Ils sont plutôt conçus pour être le plus petit possible, afin d’illustrer un seul concept ou une seule fonctionnalité. Ils ne doivent pas occuper plus d’un écran de code.

Les exemples sont stockés dans le dépôt dotnet/samples. Nous élaborons actuellement un modèle dans lequel notre structure de dossier samples correspond à notre structure de dossier docs. Voici les normes que nous appliquons :

• Les dossiers de niveau supérieur correspondent aux dossiers de niveau supérieur du dépôt docs. Par exemple, le référentiel docs contient un dossier machine-learning/tutorials, et les échantillons pour les tutoriels Machine Learning se trouvent dans le dossier samples/machine-learning/tutorials.

En outre, tous les échantillons dans les dossiers core et standard doivent pouvoir être créés et exécutés sur toutes les plateformes prises en charge par .NET Core. Notre système d’intégration continue appliquera cette stratégie. Le dossier framework de niveau supérieur contient des échantillons uniquement créés et validés sous Windows.

Les exemples de projets doivent pouvoir être générés et exécutés sur la gamme de plateformes la plus large possible pour un exemple donné. En pratique, cela signifie que vous devez générer dans la mesure du possible des applications console .NET Core. Les exemples qui sont propres au web ou à un framework d’interface utilisateur (applications web, applications mobiles, applications WPF ou WinForms, entre autres) doivent ajouter ces outils si nécessaire.

Nous essayons actuellement de mettre en place un système d’intégration continue pour tout le code. Quand vous effectuez une mise à jour d’un exemple de code, veillez à ce qu’elle fasse partie d’un projet pouvant être généré. Dans l’idéal, ajoutez également des tests pour vérifier que les exemples de code sont corrects.

Chaque échantillon complet que vous créez doit contenir un fichier readme.md. Ce fichier doit contenir une brève description de l’échantillon (un ou deux paragraphes). Votre fichier readme.md doit indiquer aux lecteurs ce qu’ils vont apprendre en explorant cet échantillon. Le fichier readme.md doit également contenir un lien vers le document en direct sur le site de documentation .NET. Pour déterminer si un fichier donné du référentiel pointe vers ce site, remplacez /docs par https://learn.microsoft.com/dotnet dans le chemin d’accès du référentiel.

Votre rubrique contiendra également des liens vers l’échantillon. Établissez un lien direct vers le dossier de l’échantillon sur GitHub.

Écrire un nouvel exemple

Les exemples sont des bibliothèques et des programmes complets destinés au téléchargement. Ils peuvent être très ciblés, mais présentent des concepts de manière à permettre aux utilisateurs d’explorer et d’expérimenter par eux-mêmes. Les instructions pour les exemples garantissent que les lecteurs peuvent télécharger et explorer. Examinez les exemples Parallel LINQ (PLINQ) comme illustration de chacune des instructions.

1. Votre exemple doit faire partie d’un projet pouvant être généré. Dans la mesure du possible, les projets doivent pouvoir être générés sur toutes les plateformes prises en charge par .NET Core. Les exceptions à cette règle sont les exemples de code qui illustrent une fonctionnalité ou un outil propre à une plateforme.

2. Pour des raisons de cohérence, votre exemple de code doit être conforme au style de codage runtime.

   De plus, nous préférons que vous utilisiez des méthodes static plutôt que des instances de méthodes quand vous illustrez quelque chose qui ne nécessite pas l’instanciation d’un nouvel objet.

3. Votre exemple de code doit inclure une gestion des exceptions appropriée. Il doit gérer toutes les exceptions susceptibles d’être levées dans le contexte de l’exemple. Par exemple, un exemple de code qui appelle la méthode Console.ReadLine pour récupérer l’entrée d’utilisateur doit utiliser une gestion des exceptions appropriée quand la chaîne d’entrée est passée en tant qu’argument à une méthode. De même, si votre exemple de code s’attend à ce qu’un appel de méthode échoue, l’exception résultante doit être gérée. Vous devez toujours gérer les exceptions spécifiques levées par la méthode, plutôt que les exceptions de classe de base telles que Exception ou SystemException.

Pour créer un exemple de code :

1. Soumettez un problème ou ajoutez un commentaire à un problème existant sur lequel vous travaillez.

2. Rédigez une rubrique qui explique les concepts illustrés par votre exemple de code (exemple : docs/standard/linq/where-clause.md).

3. Rédigez votre exemple de code (exemple : WhereClause-Sample1.cs).

4. Créez un fichier Program.cs avec un point d’entrée Main qui appelle votre exemple de code. S’il y en a déjà un, ajoutez l’appel à votre exemple :

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

Vous devez générer tout exemple ou extrait de code .NET à l’aide de l’interface de ligne de commande .NET, que vous pouvez installer avec le SDK .NET. Pour générer et exécuter votre exemple de code :

1. Accédez au dossier de l’exemple et générez-le afin de vérifier s’il existe des erreurs :

   dotnet build
   

2. Exécutez votre exemple de code :

   dotnet run
   

3. Ajoutez un fichier readme.md au répertoire racine de votre exemple.

   Il doit inclure une brève description du code et renvoyer le lecteur à l’article qui référence l’exemple. La partie supérieure du readme.md doit avoir les métadonnées nécessaires pour le navigateur d’exemples. Le bloc d’en-tête doit contenir les champs suivants :

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • La collection languages doit inclure uniquement les langages disponibles pour votre exemple.
   • La collection products doit inclure uniquement les produits appropriés à votre exemple.

Sauf indication contraire, tous les exemples de code doivent pouvoir être générés à partir de la ligne de commande sur n’importe quelle plateforme prise en charge par .NET. Il existe quelques exemples de code qui sont propres à Visual Studio et nécessitent Visual Studio 2017 ou version ultérieure. De plus, certains exemples illustrent des fonctionnalités propres à une plateforme, et nécessiteront une plateforme spécifique. D’autres exemples et extraits de code nécessitent le .NET Framework, et s’exécuteront sur des plateformes Windows et nécessiteront le Pack du développeur pour la version cible de .Net Framework.

L’expérience interactive C#

Tous les extraits de code inclus dans un article utilisent une balise de langage qui indique le langage source. Les extraits de code courts en C# peuvent utiliser la balise de langage csharp-interactive pour spécifier un extrait de code C# qui s’exécute dans le navigateur. (Les extraits de code inline utilisent la balise csharp-interactive. Pour les extraits de code inclus à partir de la source, utilisez la balise code-csharp-interactive.) Ces extraits de code affichent une fenêtre de code et une fenêtre de sortie dans l’article. La fenêtre de sortie affiche toute sortie d’exécution du code interactif une fois que l’utilisateur a exécuté l’extrait de code.

L’expérience interactive C# change la façon dont nous travaillons avec nos extraits de code. Les visiteurs peuvent exécuter l’extrait de code pour voir les résultats. Plusieurs facteurs contribuent à déterminer si l’extrait de code ou le texte correspondant doivent inclure des informations sur la sortie.

Quand faut-il afficher la sortie attendue sans exécuter l’extrait de code ?

• Les articles destinés aux débutants doivent fournir une sortie permettant aux lecteurs de comparer la sortie de leur travail avec la réponse attendue.
• Les extraits de code pour lesquels la sortie est intégrée à la rubrique doivent afficher cette sortie. Par exemple, les articles relatifs au texte mis en forme doivent montrer le format du texte sans qu’il soit nécessaire d’exécuter l’extrait de code.
• Quand l’extrait de code et la sortie attendue sont tous les deux courts, vous pouvez afficher la sortie. Cela permet de gagner un peu de temps.
• Les articles expliquant comment une culture actuelle ou invariante affecte la sortie doivent expliquer la sortie attendue. La fenêtre REPL (Read Evaluate Print Loop) interactive s’exécute sur un ordinateur hôte sous Linux. La culture par défaut et la culture invariante produisent une sortie différente sur divers systèmes d’exploitation et ordinateurs. L’article doit expliquer la sortie dans les systèmes Windows, Linux et Mac.

Quand faut-il ne pas inclure la sortie attendue dans l’extrait de code ?

• Les articles dont l’extrait de code génère une longue sortie ne doivent pas l’inclure dans les commentaires. Cela obscurcit le code une fois que l’extrait a été exécuté.
• Dans les articles dont l’extrait illustre une rubrique, mais pour lesquels la sortie n’est pas essentielle à la compréhension. Par exemple, le code exécute une requête LINQ pour expliquer la syntaxe de la requête et affiche chaque élément dans la collection en sortie.

Contribuer à du contenu dans une autre langue que l’anglais

Actuellement, les contributions au contenu traduit par une machine (MT) ne sont pas acceptées. Dans le but d’améliorer la qualité du contenu MT, nous sommes passés à un moteur MT neuronal. Nous acceptons et encourageons les contributions au contenu traduit par l’homme (HT), qui est utilisé pour entraîner le moteur MT neuronal. Ainsi, au fur et à mesure, les contributions au contenu HT vont améliorer la qualité du contenu à la fois HT et MT. Les rubriques MT présentent une clause d’exclusion de responsabilité indiquant qu’une partie peut être en MT et le bouton Modifier ne s’affiche pas parce que la modification est désactivée.

Contrat de licence du contributeur

Vous devez signer le contrat de licence de contribution (CLA) .NET Foundation avant de fusionner votre demande de tirage. Vous ne devez le faire qu’une fois pour tous les projets .NET Foundation. Vous pouvez en savoir plus sur les contrats de licence de contribution (CLA) sur Wikipédia.

Le contrat : .NET Foundation Contributor License Agreement (CLA)

Vous n’êtes pas obligé de signer le contrat au préalable. Vous pouvez cloner, dupliquer (fork) et envoyer votre demande de tirage comme d’habitude. Quand votre demande de tirage est créée, elle est classifiée par un bot CLA. Si le changement est mineur (par exemple, vous avez corrigé une faute de frappe), la demande de tirage est libellée avec cla-not-required. Dans le cas contraire, elle est classifiée cla-required. Une fois que vous avez signé le contrat CLA, les demandes de tirage actuelles et futures sont étiquetées cla-signed.