Hello,
Quelles sont les bonnes pratiques pour le fichier README d’un projet open source ?
Que faut-il mettre ou ne pas mettre ? Avez-vous de bons exemples ?
Merci !
Hello,
Pour être un utilisateur régulier, plusieurs choses me semblent importantes :
- Des instructions claires pour utiliser le projet (lib, tool,) : où sont les binaires et comment l’installer
- Utiliser des badges (genre http://shields.io/) pour illustrer rapidement le status du projet : downloads, code coverage, version, CI/Build status, …
- Des explications (claires et concises) sur les raisons et possibilités. Parfois c’est un peu verbeux donc on peut pointer vers les pages GitHub (simple et gratuit)
- Comment contribuer : quand et comment créer issue /PR. Tous les projets n’ont pas la même façon de percevoir ces contributions.
- Comment builder le projet pour les contributeurs/clone/fork
Ces choses me semblent essentielles. Pas besoin de tout avoir au début.
4 « J'aime »
J’ajouterai la mention de la licence bien visible, pour pas avoir à fouiller le projet entier et finir par s’apercevoir qu’on ne peut pas l’utiliser ;)
4 « J'aime »
Salut,
- Nom du projet
- Auteur et copyright
- État du projet
- Rapide description
- Mise ne place, utilisation rapide
- Licence(s)
- Documentation courte et/ou page pointant vers documentation longue (ou page d’exemple)
- Méthode de rapport de bug, contribution
Il faut en mettre un à mon avis. Quelquesoit le projet (me pas open source).
1 « J'aime »
Et une Contributor Covenant / Code of Conduct si on tente de faire quelque chose de propre et d’inclusif, et si on s’y tient :)
Un lien vers le site principal s’il y a, et potentiellement un rappel des communautés (Gitter, Slack, Discourse).
Quelques exemples de commandes c’est plutôt cool et apprécié.
Et, ça n’est pas dans le README mais très pratique : des issues bien tagguées pour les contributeurs débutants !
1 « J'aime »
Je passe beaucoup de temps sur Github et surtout les trendings de Github. Pour moi il y a 2 visions du README et l’une d’entre elle est la vitrine du projet. Ainsi ce que j’attends d’un bon README c’est de comprendre en quelque seconde quel est le but du projet, une petit entête parlant, un screenshot si nécessaire.
Car bon il faut être réaliste y’a des dizaines voir plus de projets qui sortent par jour, et personnellement je n’ai pas forcément beaucoup de temps à accorder à un projet. Les premières secondes (impressions) sont importantes, si le README me parle pas n’espère pas que j’irai cliquer sur un lien vers un site pour de plus ample information ; je ferme l’onglet et je passe à autre chose.
Après il y a le second aspect plus orienté développement que les gens ont déjà parlé ci dessus : contribution, licence, sample, etc.
1 « J'aime »