Template de demande de fonctionnalité qui devient changelog
7 min de lecture
Une template de demande de fonctionnalité est un formulaire avec quatre questions : ce que la personne essaie de faire, ce qui l’en empêche, ce qu’elle a essayé à la place, et comment elle veut être prévenue quand c’est fait. Tout le reste qui apparaît généralement sur une, sélecteurs de priorité, estimations d’effort, scores de valeur business, est pour l’équipe qui reçoit la demande, et c’est mal rempli par celle qui l’envoie.
Les demandes bien rangées sont le mauvais test pour une template. Le bon : six mois plus tard, quand la fonctionnalité est livrée, quelqu’un peut-il trouver la demande, la comprendre, et prévenir la personne qui l’a écrite ? La plupart des templates sont conçues pour l’accueil. Celle-ci est conçue pour le jour où la boucle se ferme.
Que devrait inclure une template de demande de fonctionnalité ?
Elle devrait inclure l’objectif, le blocage, la solution de contournement, et un moyen de revenir vers la demandeuse. Quatre champs, dans cet ordre, chacun répond à une question que l’équipe posera plus tard.
| Champ | La question à laquelle il répond plus tard | Pourquoi il est dans le formulaire |
|---|---|---|
| Qu’essayez-vous de faire ? | La fonctionnalité construite est-elle celle qu’il fallait ? | L’objectif survit à toute proposition concrète |
| Qu’est-ce qui vous en empêche aujourd’hui ? | À quoi ressemble “terminé” ? | Nomme le vide sans prescrire la correction |
| Que faites-vous à la place ? | À quel point est-ce vraiment urgent ? | Une solution de contournement douloureuse est un signal plus fort qu’un sélecteur de priorité |
| Comment devrions-nous vous prévenir ? | Qui reçoit le message “livré” ? | Le champ que la plupart des templates omettent |
Ce qui manque délibérément : une solution proposée comme champ obligatoire (bienvenue en commentaire, fausse comme cadrage), un sélecteur de priorité (chaque soumetteur choisit haute), et toute estimation d’effort ou de valeur (travail de l’équipe, après le tri). Une template qui demande une solution reçoit des demandes de boutons ; une template qui demande un objectif reçoit des demandes de résultats, et c’est sur des résultats qu’on écrit une entrée de changelog.
La template
Voici la template d’issue GitHub qu’on utilise, sous forme de formulaire. Collez-la dans
.github/ISSUE_TEMPLATE/feature_request.yml et elle se rend comme formulaire structuré sur la page
de nouvelle issue. Les demandes classées via elle atterrissent comme des issues avec les mêmes
champs que celles classées depuis un widget de feedback, ce qui compte pour la section suivante.
name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
- type: textarea
id: goal
attributes:
label: What are you trying to do?
description: >-
The outcome, not the button. "Export a month of invoices as one
PDF" beats "add a PDF export".
validations:
required: true
- type: textarea
id: blocker
attributes:
label: What stops you today?
description: >-
Where the product runs out. An error, a missing option, a limit.
validations:
required: true
- type: textarea
id: workaround
attributes:
label: What do you do instead?
description: >-
The spreadsheet, the script, the manual step. "Nothing, I gave
up" is a valid answer.
- type: input
id: contact
attributes:
label: How should we tell you when it ships?
description: >-
An email address, or leave blank to be notified only on this
issue.Deux détails font le travail. labels: ["feature-request"] signifie que la demande est classifiée
à la création plutôt que d’attendre que quelqu’un la trie. Et le dernier champ existe parce que “on
te préviendra” est une promesse, et une promesse a besoin d’une adresse.
Quels labels une demande de fonctionnalité devrait-elle porter ?
Une demande de fonctionnalité devrait porter un label pour ce qu’elle est, un pour son urgence, et un pour d’où elle vient. Trois labels, trois axes, et chacun est lu par une lectrice différente.
| Label | Valeurs | Qui le lit |
|---|---|---|
| Type | feature-request, bug | Qui décide dans quelle file elle entre |
| Priorité | priority:low, priority:medium, priority:high | Qui planifie le prochain cycle |
| Source | from-widget, from-form, from-support | Qui mesure d’où viennent les demandes |
Le widget applique les deux premiers axes et from-widget quand il classe une soumission comme
issue ; from-form et from-support sont des suggestions pour les demandes qui arrivent par
d’autres voies. Les labels du widget sont un type (bug ou feature-request, décidé par un classificateur à partir du seul
message), une priorité (un rapport de crash calme et précis est haut ; un doublon de quelque chose
déjà demandé est bas ; tout ce qui suggère même vaguement un problème de sécurité est bug et
haut, quelle que soit la formulation), et from-widget. Les mêmes trois axes fonctionnent pour les
demandes qui arrivent à la main via la template ci-dessus, et c’est le point : une demande est une
demande, peu importe par où elle est entrée.
Une convention de plus : le widget retire l’adresse email de la personne qui soumet du corps de l’issue avant de la classer, parce que l’issue vit dans un repository qui peut être public, et la remplace par une référence de soumission. L’adresse reste hors de l’issue ; la personne qui soumet suit le résultat dans le widget lui-même. Faites de même avec le champ de contact si votre tracker est visible pour des gens hors de l’équipe.
Comment une demande de fonctionnalité devient-elle une entrée de changelog ?
Une demande de fonctionnalité devient une entrée de changelog quand une pull request ferme
l’issue et que l’entrée rédigée à partir de cette pull request lie en retour. Le mécanisme, ce sont
les propres mots-clés de fermeture de GitHub : une PR dont la description dit Fixes #142 ferme
l’issue 142 au merge. Si vos entrées de changelog sont rédigées à partir de pull requests mergées,
le brouillon peut porter le numéro d’issue avec lui, et l’entrée sait qui a demandé.
C’est la raison pour laquelle la template demande l’objectif plutôt que la solution. Quand l’entrée est écrite, l’objectif est la phrase dont a besoin qui écrit : “Vous pouvez maintenant exporter un mois de factures comme un seul PDF” est une entrée de changelog. “Ajout de l’export PDF” est un message de commit. Les outils de changelog qui rédigent à partir de pull requests peuvent faire la collecte et le lien ; la formulation a toujours besoin d’une personne, et la personne a besoin de l’objectif.
Que se passe-t-il quand c’est livré ?
La demandeuse est prévenue, avec un lien vers l’entrée. Dans notre configuration, c’est automatique pour les demandes arrivées via le widget : un commentaire disant “Shipped — <titre de l’entrée>” avec un lien vers l’entrée publiée, posté sur l’issue dès qu’une personne approuve l’entrée, pendant que le widget montre la même entrée à la personne qui l’a soumise. Une issue créée à la main depuis cette template ne reçoit aucun commentaire automatique ; fermez cette boucle vous-même, selon la même règle. Le commentaire est posté délibérément à l’approbation plutôt qu’au merge : un commentaire disant que quelque chose est en prod avant que ce le soit est une promesse rompue avec horodatage. Chaque demande est notifiée au plus une fois ; une seconde approbation de la même entrée ne produit pas un second commentaire.
Si vous faites ça à la main, la même règle s’applique. Ne fermez pas la boucle depuis la pull request. Fermez-la depuis l’entrée publiée, et fermez-la une fois. Feed et widget portent la même entrée à tous ceux qui n’ont pas demandé, qui sont la plupart ; le commentaire est pour ceux qui ont demandé.
Pourquoi la plupart des templates de demande de fonctionnalité échouent
Elles sont conçues pour faciliter le tri et y réussissent, au prix du seul moment qui compte pour la demandeuse. Une template avec douze champs reçoit moins de demandes, et celles qu’elle reçoit viennent de gens avec la patience de remplir douze champs, ce qui n’est pas la même population que celle qui a besoin de la fonctionnalité. Une template avec quatre champs, dont un “comment vous contactons-nous”, reçoit plus de demandes et peut toutes les honorer.
FAQ
Une template de demande de fonctionnalité devrait-elle demander la priorité ? Non. Demandez plutôt la solution de contournement. “J’exporte vers un tableur et je le ressaisis chaque vendredi” en dit plus sur la priorité qu’un menu déroulant que la personne qui a soumis a mis sur haute.
Les demandeurs devraient-ils proposer une solution ? Ils peuvent, dans le texte libre. N’en faites pas le cadrage. Les demandes écrites comme des solutions sont plus difficiles à fusionner entre elles et plus difficiles à transformer en entrée de changelog.
Les demandes de fonctionnalité devraient-elles apparaître sur une roadmap publique ? Une fois planifiées, oui : un label sur la même issue la met dans la colonne planifiée, et la demandeuse peut voir comment elle avance. L’article roadmap publique est le mécanisme.
Comment gérer les doublons ?
Liez la nouvelle demande à l’issue existante et étiquetez-la priorité basse ; ne la fermez pas.
Chaque doublon est une personne de plus à prévenir quand c’est livré. Avec le commentaire
automatique de changeloop, cette personne n’est prévenue que si la pull request nomme aussi son
issue (Fixes #142, fixes #187).
Où devrait vivre la template ? Dans le repository qui recevra la pull request, pour que le mot-clé de fermeture fonctionne. Une demande dans un tracker séparé doit être liée à la main au merge, et c’est cette étape qui est sautée.
Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.