Faites un README
Suggestions pour un bon README
chaque projet est différent, alors considérez laquelle de ces sections s’applique au vôtre. Les sections utilisées dans le modèle sont des suggestions pour la plupart des projets open source. Gardez également à l’esprit que même si un README peut être trop long et détaillé, trop long vaut mieux que trop court. Si vous pensez que votre README est trop long, envisagez d’utiliser une autre forme de documentation plutôt que de couper des informations.
Nom
Choisissez une auto-explicatif nom pour votre projet.,
Description
faites savoir aux gens ce que votre projet peut faire spécifiquement. Fournissez un contexte et ajoutez un lien vers toute référence que les visiteurs ne connaissent pas. Une liste de fonctionnalités ou une sous-section D’arrière-plan peut également être ajoutée ici. S’il existe des alternatives à votre projet, c’est un bon endroit pour énumérer les facteurs de différenciation.
Badges
sur certains READMEs, vous pouvez voir de petites images qui transmettent des métadonnées, par exemple si tous les tests sont réussis ou non pour le projet. Vous pouvez utiliser des boucliers pour en ajouter à votre README. De nombreux services ont également des instructions pour ajouter un badge.,
visuels
selon ce que vous faites, il peut être une bonne idée d’inclure des captures d’écran ou même une vidéo (vous verrez souvent des GIF plutôt que des vidéos réelles). Des outils comme ttygif peuvent vous aider, mais consultez Asciinema pour une méthode plus sophistiquée.
Installation
Dans un écosystème particulier, il peut y avoir une façon courante d’installer des choses, comme l’utilisation de Yarn, NuGet ou Homebrew. Cependant, considérez la possibilité que celui qui lit votre README soit un novice et aimerait plus de conseils., La liste des étapes spécifiques aide à éliminer l’ambiguïté et permet aux utilisateurs d’utiliser votre projet le plus rapidement possible. S’il ne s’exécute que dans un contexte spécifique, comme une version de langage de programmation ou un système d’exploitation particulier, ou s’il a des dépendances qui doivent être installées manuellement, ajoutez également une sous-section Exigences.
utilisation
utilisez généreusement des exemples et affichez la sortie attendue si vous le pouvez. Il est utile d « avoir en ligne Le plus petit exemple d » utilisation que vous pouvez démontrer, tout en fournissant des liens vers des exemples plus sophistiqués s » ils sont trop longs pour être raisonnablement inclus dans le README.,
Soutien
Dire aux gens où ils peuvent aller pour obtenir de l’aide. Il peut être n’importe quelle combinaison d’un outil de suivi, d’une salle de chat, une adresse e-mail, etc.
Roadmap
Si vous avez des idées pour des versions à l’avenir, c’est une bonne idée de les lister dans le fichier README.
contribution
indiquez si vous êtes ouvert aux contributions et quelles sont vos exigences pour les accepter.
Pour les personnes qui veulent apporter des modifications à votre projet, il est utile d’avoir de la documentation sur la façon d’obtenir commencé., Il y a peut-être un script qu’ils devraient exécuter ou des variables d’environnement qu’ils doivent définir. Faire ces étapes explicites. Ces instructions pourraient également être utiles à votre futur moi.
Vous pouvez également documenter les commandes pour Linter le code ou exécuter des tests. Ces étapes aident à garantir une qualité de code élevée et à réduire la probabilité que les modifications cassent quelque chose par inadvertance. Avoir des instructions pour exécuter des tests est particulièrement utile si cela nécessite une configuration externe, comme le démarrage d’un serveur Selenium pour les tests dans un navigateur.,
auteurs et remerciements
Montrez votre reconnaissance à ceux qui ont contribué au projet.
Licence
Pour les projets open source, dire comment il est licencié.
État du projet
Si vous avez manqué d’énergie ou de temps pour votre projet, mettez une note en haut du README indiquant que le développement a ralenti ou s’est complètement arrêté. Quelqu’un peut choisir de fork votre projet ou de se porter volontaire pour intervenir en tant que mainteneur ou propriétaire, permettant à votre projet de continuer. Vous pouvez également faire une demande explicite pour les responsables.