Šablona požadavku na funkci, která se stává changelogem

Šablona požadavku na funkci je formulář se čtyřmi otázkami: co se osoba snaží udělat, co jí v tom brání, co zkusila místo toho, a jak chce být informována, až to bude hotové. Vše ostatní, co se obvykle na jednom takovém objeví, selektory priority, odhady úsilí, body obchodní hodnoty, je pro tým přijímající požadavek, a špatně to vyplňuje odesílatel.

Uspořádané požadavky jsou špatný test pro šablonu. Ten správný: o šest měsíců později, když je funkce vydána, může někdo najít požadavek, pochopit ho, a informovat osobu, která ho napsala? Většina šablon je navržena pro příjem. Tahle je navržena pro den, kdy se smyčka uzavírá.

Co by měla šablona požadavku na funkci obsahovat?

Měla by obsahovat cíl, blokátor, náhradní řešení, a cestu zpět k žadateli. Čtyři pole, v tomto pořadí, každé odpovídá na otázku, kterou tým položí později.

Co je záměrně vynecháno: navržené řešení jako povinné pole (vítané jako komentář, špatné jako rámec), selektor priority (každý odesílatel volí vysokou), a jakýkoli odhad úsilí nebo hodnoty (úkol týmu, po třídění). Šablona, která žádá o řešení, dostává požadavky na tlačítka; šablona, která žádá o cíl, dostává požadavky na výsledky, a o výsledcích se píše záznam changelogu.

Šablona

Toto je šablona issue GitHub, kterou používáme, jako formulář. Vložte ji do .github/ISSUE_TEMPLATE/feature_request.yml, a vykreslí se jako strukturovaný formulář na stránce nového issue. Požadavky podané přes ni přistávají jako issue se stejnými poli jako ty podané z widgetu zpětné vazby, což záleží pro další sekci.

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.

Dva detaily dělají práci. labels: ["feature-request"] znamená, že se požadavek klasifikuje při vytvoření, místo čekání, až ho někdo roztřídí. A poslední pole existuje, protože «dáme vám vědět» je slib, a slib potřebuje adresu.

Jaké štítky by měl nést požadavek na funkci?

Požadavek na funkci by měl nést jeden štítek pro to, čím je, jeden pro to, jak je naléhavý, a jeden pro to, odkud přišel. Tři štítky, tři osy, a každý čte jiná čtenářka.

Widget aplikuje první dvě osy a from-widget, když podává odeslání jako issue; from-form a from-support jsou návrhy pro požadavky, které přicházejí jinými cestami. Štítky widgetu jsou typ (bug nebo feature-request, rozhodnutý klasifikátorem jen ze zprávy), priorita (klidná, konkrétní zpráva o havárii je vysoká; duplikát něčeho už dotazovaného je nízká; cokoli, co i jen naznačuje bezpečnostní problém, je bug a vysoká, bez ohledu na formulaci), a from-widget. Stejné tři osy fungují pro požadavky, které přicházejí ručně přes šablonu výše, a to je ta podstata: požadavek je požadavek, ať přišel odkudkoli.

Ještě jedna konvence: widget odstraní e-mailovou adresu odesílatele z těla issue před podáním, protože issue žije v repozitáři, který může být veřejný, a nahradí ji referencí na odeslání. Adresa zůstává mimo issue; odesílatel sleduje výsledek přímo ve widgetu. Udělejte totéž s kontaktním polem, pokud je váš tracker viditelný pro lidi mimo tým.

Jak se požadavek na funkci stane záznamem changelogu?

Požadavek na funkci se stane záznamem changelogu, když pull request uzavře issue, a záznam sestavený z tohoto pull requestu odkazuje zpět. Mechanismem jsou vlastní klíčová slova pro uzavření od GitHubu: PR, jehož popis říká Fixes #142, uzavře issue 142 při merge. Pokud jsou vaše záznamy changelogu sestavovány ze sloučených pull requestů, koncept může nést číslo issue s sebou, a záznam ví, kdo se ptal.

To je důvod, proč šablona žádá o cíl místo řešení. Když se záznam píše, cíl je věta, kterou autor potřebuje: «Nyní můžete exportovat měsíc faktur jako jeden PDF» je záznam changelogu. «Přidán export PDF» je zpráva commitu. Nástroje pro changelog, které sestavují záznamy z pull requestů, mohou provést sběr a odkaz; formulace stále potřebuje člověka, a člověk potřebuje cíl.

Co se stane, když je to vydáno?

Žadatel je informován, s odkazem na záznam. V naší konfiguraci je to automatické u požadavků, které přišly přes widget: komentář, který říká «Shipped — <titulek záznamu>» s odkazem na zveřejněný záznam, umístěný na issue, jakmile člověk záznam schválí, zatímco widget odesílateli ukáže stejný záznam. Issue podané ručně z této šablony nedostane automatický komentář; tuhle smyčku uzavřete sami, podle stejného pravidla. Komentář je záměrně umístěn při schválení, ne při merge: komentář, který říká, že něco je na živo, než tomu tak je, je porušený slib s časovým razítkem. Každý požadavek je informován nejvýše jednou; druhé schválení stejného záznamu neproduje druhý komentář.

Pokud to děláte ručně, platí stejné pravidlo. Neuzavírejte smyčku z pull requestu. Uzavřete ji ze zveřejněného záznamu, a uzavřete ji jednou. Kanál a widget nesou stejný záznam všem, kteří se neptali, což je většina; komentář je pro ty, kteří se ptali.

Proč většina šablon požadavků na funkce selhává

Jsou navrženy tak, aby usnadnily třídění, a to se jim daří, za cenu jediného okamžiku, na kterém záleží žadateli. Šablona s dvanácti poli dostává méně požadavků, a ty, které dostane, přicházejí od lidí s trpělivostí vyplnit dvanáct polí, což není stejná populace jako ta, která funkci potřebuje. Šablona se čtyřmi poli, z nichž jedno je «jak vás kontaktovat», dostává více požadavků a může uctít každý z nich.

FAQ

Měla by šablona požadavku na funkci žádat o prioritu? Ne. Ptejte se místo toho na náhradní řešení. «Exportuji do tabulky a přepisuji ji každý pátek» říká o prioritě víc než rozbalovací nabídka, kterou odesílatel nastavil na vysokou.

Měli by žadatelé navrhovat řešení? Mohou, ve volném textu. Nedělejte z toho rámec. Požadavky napsané jako řešení se hůř slučují navzájem a hůř mění na záznam changelogu.

Měly by se požadavky na funkce objevovat na veřejné roadmapě? Po naplánování ano: štítek na stejném issue ho umístí do sloupce plánováno, a žadatel může vidět, jak se pohybuje. Článek veřejná roadmap je ten mechanismus.

Jak zacházet s duplicitami? Propojte nový požadavek s existujícím issue a označte ho nízkou prioritou; nezavírejte ho. Každá duplicita je další osoba k informování při vydání. S automatickým komentářem Changeloop se ta osoba dozví jen tehdy, když pull request uvádí i její issue (Fixes #142, fixes #187).

Kde by měla šablona žít? V repozitáři, který přijme pull request, aby fungovalo klíčové slovo pro uzavření. Požadavek v odděleném trackeru musí být propojen ručně při merge, a to je ten krok, který se přeskakuje.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Dokumentace pro vývojáře, Srovnání nástrojů pro changelog