Feature-request-template die changelog wordt

Een feature-request-template is een formulier met vier vragen: wat probeert de persoon te doen, wat houdt haar tegen, wat probeerde ze in plaats daarvan, en hoe wil ze ingelicht worden wanneer het klaar is. Al het andere dat meestal op zo’n formulier staat, prioriteitskeuzes, inschattingen van inspanning, business-value-scores, is voor het team dat het verzoek ontvangt, en wordt verkeerd ingevuld door de indiener.

Nette verzoeken zijn de verkeerde test voor een template. De juiste: zes maanden later, wanneer de feature wordt uitgebracht, kan iemand het verzoek vinden, het begrijpen, en de schrijfster inlichten? De meeste templates zijn ontworpen voor intake. Deze is ontworpen voor de dag waarop de loop sluit.

Wat zou een feature-request-template moeten bevatten?

Hij zou het doel, de blokkade, de workaround, en een weg terug naar de aanvrager moeten bevatten. Vier velden, in die volgorde, elk beantwoordt een vraag die het team later zal stellen.

Wat er bewust ontbreekt: een voorgestelde oplossing als verplicht veld (welkom als commentaar, verkeerd als kader), een prioriteitskeuze (elke indiener kiest hoog), en elke inschatting van inspanning of waarde (taak van het team, na de triage). Een template die om een oplossing vraagt krijgt verzoeken voor knoppen; een template die om een doel vraagt krijgt verzoeken voor resultaten, en over resultaten schrijf je een changelog-entry.

De template

Dit is de GitHub-issue-template die wij gebruiken, als formulier. Plak hem in .github/ISSUE_TEMPLATE/feature_request.yml en hij wordt weergegeven als gestructureerd formulier op de nieuwe-issue-pagina. Verzoeken ingediend via dit formulier landen als issues met dezelfde velden als die ingediend vanuit een feedbackwidget, wat ertoe doet voor de volgende sectie.

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.

Twee details doen het werk. labels: ["feature-request"] betekent dat het verzoek bij aanmaak wordt geclassificeerd in plaats van te wachten tot iemand het trieert. En het laatste veld bestaat omdat “we laten het je weten” een belofte is, en een belofte heeft een adres nodig.

Welke labels zou een feature-verzoek moeten dragen?

Een feature-verzoek zou een label moeten dragen voor wat het is, een voor hoe urgent het is, en een voor waar het vandaan komt. Drie labels, drie assen, en elk wordt door een andere lezer gelezen.

De widget past de eerste twee assen en from-widget toe wanneer die een inzending als issue registreert; from-form en from-support zijn suggesties voor verzoeken die via andere wegen binnenkomen. De labels van de widget zijn een soort (bug of feature-request, beslist door een classifier alleen op basis van het bericht), een prioriteit (een kalm, specifiek crashrapport is hoog; een duplicaat van iets al gevraagd is laag; alles wat zelfs maar suggereert een securityprobleem te zijn is bug en hoog, ongeacht de formulering), en from-widget. Dezelfde drie assen werken voor verzoeken die met de hand binnenkomen via de bovenstaande template, en dat is het punt: een verzoek is een verzoek, waar het ook binnenkwam.

Nog een conventie: de widget verwijdert het e-mailadres van de indiener uit de issue-body voordat hij hem registreert, omdat de issue in een repository leeft die publiek kan zijn, en vervangt het door een indieningsreferentie. Het adres blijft buiten de issue; de indiener volgt de uitkomst in de widget zelf. Doe hetzelfde met het contactveld als jullie tracker zichtbaar is voor mensen buiten het team.

Hoe wordt een feature-verzoek een changelog-entry?

Een feature-verzoek wordt een changelog-entry wanneer een pull request de issue sluit en de entry die uit die pull request is opgesteld terug linkt. Het mechanisme zijn GitHubs eigen sluitwoorden: een PR waarvan de beschrijving Fixes #142 zegt sluit issue 142 bij de merge. Als jullie changelog-entries worden opgesteld uit gemergede pull requests, kan het concept het issue-nummer meedragen, en weet de entry wie vroeg.

Dat is de reden waarom de template om het doel vraagt in plaats van de oplossing. Wanneer de entry wordt geschreven, is het doel de zin die de schrijver nodig heeft: “Je kunt nu een maand facturen exporteren als één PDF” is een changelog-entry. “PDF-export toegevoegd” is een commitbericht. De changelog-tools die opstellen uit pull requests kunnen de verzameling en de link doen; de formulering heeft nog steeds een mens nodig, en de mens heeft het doel nodig.

Wat gebeurt er wanneer het wordt uitgebracht?

De aanvrager wordt ingelicht, met een link naar de entry. In onze opzet gebeurt dat automatisch voor verzoeken die via de widget binnenkwamen: een reactie die “Shipped — ” zegt met een link naar de gepubliceerde entry, geplaatst op de issue zodra een mens de entry heeft goedgekeurd, terwijl de widget de indiener dezelfde entry toont. Een issue die met de hand vanuit deze template is aangemaakt, krijgt geen automatische reactie; sluit die loop zelf, volgens dezelfde regel. De reactie wordt bewust geplaatst bij goedkeuring in plaats van bij de merge: een reactie die zegt dat iets live is voordat het dat is, is een gebroken belofte met tijdstempel. Elk verzoek wordt hoogstens één keer genotificeerd; een tweede goedkeuring van dezelfde entry produceert geen tweede reactie.

Als jullie dit met de hand doen, geldt dezelfde regel. Sluit de loop niet vanuit de pull request. Sluit hem vanuit de gepubliceerde entry, en sluit hem één keer. Feed en widget dragen dezelfde entry naar iedereen die niet vroeg, wat de meesten zijn; de reactie is voor wie vroeg.

Waarom de meeste feature-request-templates falen

Ze zijn ontworpen om triage makkelijker te maken en dat lukt, ten koste van het enige moment dat ertoe doet voor de aanvrager. Een template met twaalf velden krijgt minder verzoeken, en degene die hij krijgt komen van mensen met het geduld om twaalf velden in te vullen, wat niet dezelfde populatie is als die de feature nodig heeft. Een template met vier velden, waarvan één “hoe bereiken we je”, krijgt meer verzoeken en kan ze allemaal eer aandoen.

FAQ

Zou een feature-request-template om prioriteit moeten vragen? Nee. Vraag in plaats daarvan naar de workaround. “Ik exporteer naar een spreadsheet en tik het elke vrijdag opnieuw in” zegt meer over prioriteit dan een keuzemenu dat de indiener op hoog zette.

Zouden aanvragers een oplossing moeten voorstellen? Dat mag, in de vrije tekst. Maak het niet het kader. Als oplossingen geformuleerde verzoeken zijn lastiger samen te voegen en lastiger om te veranderen in een changelog-entry.

Zouden feature-verzoeken op een publieke roadmap moeten verschijnen? Zodra ze gepland zijn, ja: een label op dezelfde issue zet hem in de geplande kolom, en de aanvrager kan zien hoe het beweegt. Het artikel publieke roadmap is het mechanisme.

Hoe ga ik om met duplicaten? Link het nieuwe verzoek aan de bestaande issue en label hem lage prioriteit; sluit hem niet. Elk duplicaat is nog een persoon om in te lichten wanneer het wordt uitgebracht. Met de automatische reactie van Changeloop wordt die persoon alleen ingelicht als de pull request ook haar issue noemt (Fixes #142, fixes #187).

Waar zou de template moeten leven? In de repository die de pull request zal ontvangen, zodat het sluitwoord werkt. Een verzoek in een aparte tracker moet met de hand worden gelinkt bij de merge, en dat is de stap die wordt overgeslagen.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Documentatie voor ontwikkelaars, Changelog-tools vergeleken