-
Notifications
You must be signed in to change notification settings - Fork 92
Comment écrire une bonne issue
- Le titre doit commencer par un verbe à l’infinitif,
- Décrire le problème, le comportement attendu, et comment reproduire,
- Au besoin mettre des liens, captures d’écrans et tout pour donner du contexte,
- Ne pas hésiter à créer des issues imparfaites, les mainteneurs du projet reformuleront.
C’est la règle générale : ça force à formuler ce qu’on veut. Le but est avant tout d’éviter l’ambiguïté comportement attendu entre comportement constaté :
Bof : Le bouton « Enregistrer le brouillon » est décalé vers la droite.
Mieux : Centrer le bouton « Enregistrer le brouillon ».
Faut-il centrer ou décaler le bouton « Enregistrer » ? Il vaut mieux être explicite.
Un autre exemple plus concret :
Bof : L’aperçu d’une procédure peut afficher les boutons d’enregistrement
Mieux : Éviter d’afficher les boutons d’enregistrement sur l’aperçu d'une procédure
Pareil, les « boutons d’enregistrement » sont-ils le bug ou le comportement attendu ?
Pour les rapports de bugs, on peut aussi écrire « Crash quand blabla » ou « X ne fonctionne pas quand Y ». Le principal est d’indiquer que c’est un problème. Ça marche aussi en choisissant des mots à connotation négative, comme « Le bouton est mal aligné. » au lieu de « Le bouton est décalé. »
Autre point important : dans les présentation en liste, on ne voit que le titre. Celui-ci doit donc suffire à comprendre l’issue.
On peut re-rédiger une issue, y compris son titre et sa description, même si elle a été créée par quelqu’un d’autre. (Même si c’est sympa de prévenir et de noter l’historique.)
Idéalement, toutes les issues sont des Actions à réaliser. Mais ça n’empêche pas de créer une issue quand on ne connait pas la solution à apporter à un problème : la discussion et les commentaires peuvent justement permettre de clarifier l’issue d’origine et de la réécrire, ou de la remplacer par une nouvelle issue qui décrie la solution à apporter.
On a toute la place pour décrire le problème, la solution et les circonstances dans la description. C’est bien d’être concis ; c’est encore mieux d’être explicite. Ne pas hésiter à mettre des liens vers :
- la conversation avec le service client,
- les tweets,
- le code concerné,
- les logs Sentry,
- etc.
Si le message au service client ou le tweet contenait des captures d’écran, autant les inclure directement dans l’issue.
Idem pour les tweets, ou les stacktraces Sentry : ils peuvent disparaitre avant que l’issue ne soit fermée, il vaut donc mieux copier les passages pertinents dans la description.
(La syntaxe Markdown de GitHub est documentée ici.)
- La syntaxe des listes à cocher permet de faire des sous-taches. Comme ceci:
* [ ] truc 1
* [ ] truc 2
- On peut référencer les issues et pull requests liées. La syntaxe est
#123, pour les issues et pour les merge requests. GitHub rajoute automatiquement une référence inverse dans l’autre sens.
Dans l’ensemble, les labels indiquent les catégories générales d’une issue — alors que les milestones indiquent une question de planning.
Pour savoir si une catégorie devrait être un label ou une milestone, une manière est de se poser la question « Est-ce que cette catégorie est bornée dans le temps » ? Si oui, c’est une milestone ; sinon, c’est un label.