Créer un fichier README pour votre dépôt

  • Article

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Votre référentiel Git doit avoir un fichier readme afin que les visionneuses sachent ce que fait votre code et comment elles peuvent commencer à l’utiliser. Votre fichier readme doit parler aux audiences suivantes :

  • Utilisateurs qui souhaitent simplement exécuter votre code.
  • Développeurs qui souhaitent générer et tester votre code. Les développeurs sont également des utilisateurs.
  • Contributeurs qui souhaitent envoyer des modifications à votre code. Les contributeurs sont des développeurs et des utilisateurs.

Écrivez votre fichier readme dans Markdown au lieu de texte brut. Markdown permet de mettre en forme facilement du texte, d’inclure des images et de créer des liens en fonction des besoins pour plus de documentation à partir de votre fichier readme.

Voici quelques excellents fichiers readme qui utilisent ce format et s’adressent aux trois audiences, pour référence et inspiration :

Créer une introduction

Démarrez votre fichier readme avec une brève explication décrivant votre projet. Ajoutez une capture d’écran ou une image GIF animée dans votre introduction si votre projet a une interface utilisateur. Si votre code s’appuie sur une autre application ou bibliothèque, veillez à indiquer ces dépendances dans l’introduction ou juste en dessous. Les applications et les outils qui s’exécutent uniquement sur des plateformes spécifiques doivent avoir les versions de système d’exploitation prises en charge indiquées dans cette section du fichier readme.

Aider vos utilisateurs à démarrer

Guidez les utilisateurs dans la mise en place de votre code sur leur propre système dans la section suivante de votre fichier readme. Restez concentré sur les étapes essentielles pour commencer à utiliser votre code. Lier les versions requises de n’importe quel logiciel prérequis afin que les utilisateurs puissent y accéder facilement. Si vous avez des étapes de configuration complexes, documentez-les en dehors de votre fichier readme et liez-les.

Indiquez où obtenir la dernière version de votre code. Un programme d’installation binaire ou des instructions sur l’utilisation de votre code par le biais d’outils d’empaquetage est préférable. Si votre projet est une bibliothèque ou une interface vers une API, placez un extrait de code montrant l’utilisation de base et affichez l’exemple de sortie du code dans cet extrait de code.

Fournir des étapes de génération pour les développeurs

Utilisez la section suivante de votre fichier readme pour montrer aux développeurs comment générer votre code à partir d’un nouveau clone du référentiel et exécuter les tests inclus. Effectuez les actions suivantes :

  • Donnez des détails sur les outils nécessaires pour générer le code et documenter les étapes à suivre pour les configurer pour obtenir une build propre.
  • Découvrez des instructions de build denses ou complexes dans une page distincte de votre documentation et liez-la si nécessaire.
  • Exécutez les instructions à mesure que vous les écrivez pour vérifier que les instructions fonctionnent pour un nouveau contributeur.

N’oubliez pas que le développeur qui s’appuie sur ces instructions pourrait être vous, après n’avoir pas travaillé sur un projet pendant un certain temps.

Fournissez les commandes pour exécuter tous les cas de test fournis avec le code source une fois la build réussie. Les développeurs s’appuient sur ces cas de test pour s’assurer qu’ils n’interrompent pas votre code au fur et à mesure qu’ils apportent des modifications. De bons cas de test servent également d’exemples que les développeurs peuvent utiliser pour générer leurs propres cas de test lors de l’ajout de nouvelles fonctionnalités.

Aider les utilisateurs à contribuer

La dernière section de votre fichier readme aide les utilisateurs et les développeurs à participer à la création de rapports de problèmes et à suggérer des idées pour améliorer votre code. Les utilisateurs doivent être liés aux canaux où ils peuvent ouvrir des bogues, demander des fonctionnalités ou obtenir de l’aide à l’aide de votre code.

Les développeurs doivent savoir quelles règles ils doivent suivre pour apporter des modifications, telles que les instructions de codage/test et les exigences relatives aux demandes de tirage. Si vous avez besoin d’un accord de contributeur pour accepter des demandes de tirage ou appliquer un code de conduite communautaire, ce processus doit être lié ou documenté dans cette section. Indiquez la licence sous laquelle le code est publié et liez le texte intégral de la licence.