Feature-Request-Vorlage, die zum Changelog-Eintrag wird

Eine Feature-Request-Vorlage ist ein Formular mit vier Fragen: Was versucht die Person zu tun, was hindert sie daran, was hat sie stattdessen probiert, und wie will sie erfahren, wenn es fertig ist. Alles andere, was normalerweise auf einer steht, Prioritäts-Dropdowns, Aufwandsschätzungen, Business-Value-Punkte, ist für das Team, das die Anfrage erhält, und wird von der einreichenden Person falsch ausgefüllt.

Ordentliche Anfragen sind der falsche Test für eine Vorlage. Der richtige: Sechs Monate später, wenn das Feature ausgeliefert wird, kann jemand die Anfrage finden, sie verstehen, und der Person, die sie geschrieben hat, Bescheid geben? Die meisten Vorlagen sind für die Aufnahme gestaltet. Diese ist für den Tag gestaltet, an dem sich der Loop schließt.

Was sollte eine Feature-Request-Vorlage enthalten?

Sie sollte das Ziel, den Blocker, den Workaround und einen Weg zurück zur anfragenden Person enthalten. Vier Felder, in dieser Reihenfolge, jedes beantwortet eine Frage, die das Team später stellen wird.

Was absichtlich fehlt: ein vorgeschlagener Lösungsweg als Pflichtfeld (als Kommentar willkommen, als Rahmung falsch), ein Prioritäts-Dropdown (jede einreichende Person wählt hoch), und jede Schätzung von Aufwand oder Wert (Aufgabe des Teams, nach der Triage). Eine Vorlage, die nach einer Lösung fragt, bekommt Anfragen für Buttons; eine Vorlage, die nach einem Ziel fragt, bekommt Anfragen für Ergebnisse, und über Ergebnisse wird ein Changelog-Eintrag geschrieben.

Die Vorlage

Das ist die GitHub-Issue-Vorlage, die wir nutzen, als Formular. Fügt sie in .github/ISSUE_TEMPLATE/feature_request.yml ein, und sie rendert als strukturiertes Formular auf der “New Issue”-Seite. Über sie eingereichte Anfragen landen als Issues mit denselben Feldern wie die, die über ein Feedback-Widget eingereicht werden, was für den nächsten Abschnitt zählt.

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.

Zwei Details leisten die Arbeit. labels: ["feature-request"] bedeutet, die Anfrage wird bei Erstellung klassifiziert, statt darauf zu warten, dass jemand sie triagiert. Und das letzte Feld existiert, weil “wir sagen dir Bescheid” ein Versprechen ist, und ein Versprechen eine Adresse braucht.

Welche Labels sollte eine Feature-Anfrage tragen?

Eine Feature-Anfrage sollte ein Label dafür tragen, was sie ist, eines dafür, wie dringend sie ist, und eines dafür, woher sie kam. Drei Labels, drei Achsen, und jede wird von einer anderen Leserin gelesen.

Das Widget wendet die ersten beiden Achsen und from-widget an, wenn es eine Einreichung als Issue ablegt; from-form und from-support sind Vorschläge für Anfragen, die auf anderen Wegen eintreffen. Die Labels des Widgets sind eine Art (bug oder feature-request, von einem Klassifikator allein aus der Nachricht entschieden), eine Priorität (ein ruhiger, konkreter Absturzbericht ist hoch; ein Duplikat von etwas bereits Gefragtem ist niedrig; alles, was auch nur andeutungsweise ein Sicherheitsproblem ist, wird bug und hoch, egal wie es formuliert ist), und from-widget. Dieselben drei Achsen funktionieren für Anfragen, die von Hand über die obige Vorlage eintreffen, und das ist der Punkt: Eine Anfrage ist eine Anfrage, egal wo sie eingegangen ist.

Noch eine Konvention: Das Widget entfernt die E-Mail-Adresse der einreichenden Person aus dem Issue-Text, bevor es ihn ablegt, weil das Issue in einem Repository liegt, das öffentlich sein kann, und ersetzt sie durch eine Einreichungsreferenz. Die Adresse bleibt aus dem Issue heraus; die einreichende Person verfolgt das Ergebnis im Widget selbst. Macht dasselbe mit dem Kontaktfeld, wenn euer Tracker für Außenstehende sichtbar ist.

Wie wird eine Feature-Anfrage zu einem Changelog-Eintrag?

Eine Feature-Anfrage wird zu einem Changelog-Eintrag, wenn ein Pull Request das Issue schließt und der aus diesem Pull Request entworfene Eintrag zurückverlinkt. Der Mechanismus sind GitHubs eigene Schließ-Schlüsselwörter: Ein PR, dessen Beschreibung Fixes #142 sagt, schließt Issue 142 beim Merge. Werden eure Changelog-Einträge aus gemergten Pull Requests entworfen, kann der Entwurf die Issue-Nummer mitführen, und der Eintrag weiß, wer gefragt hat.

Das ist der Grund, warum die Vorlage nach dem Ziel statt nach der Lösung fragt. Wenn der Eintrag geschrieben wird, ist das Ziel der Satz, den die schreibende Person braucht: “Du kannst jetzt einen Monat Rechnungen als eine PDF exportieren” ist ein Changelog-Eintrag. “PDF-Export hinzugefügt” ist eine Commit-Nachricht. Die Changelog-Tools, die aus Pull Requests entwerfen, können das Sammeln und Verlinken erledigen; die Formulierung braucht immer noch einen Menschen, und der Mensch braucht das Ziel.

Was passiert, wenn es ausgeliefert wird?

Die anfragende Person bekommt Bescheid, mit Link zum Eintrag. In unserem Setup passiert das automatisch für Anfragen, die über das Widget kamen: ein Kommentar mit “Shipped — ” und Link zum veröffentlichten Eintrag, gepostet auf dem Issue, sobald ein Mensch den Eintrag freigegeben hat, während das Widget der einreichenden Person denselben Eintrag zeigt. Ein von Hand aus dieser Vorlage angelegtes Issue bekommt keinen automatischen Kommentar; schließt diesen Loop selbst, nach derselben Regel. Der Kommentar wird absichtlich bei Freigabe gepostet, nicht beim Merge: ein Kommentar, der sagt, etwas sei live, bevor es live ist, ist ein gebrochenes Versprechen mit Zeitstempel. Jede Anfrage wird höchstens einmal benachrichtigt; eine zweite Freigabe desselben Eintrags erzeugt keinen zweiten Kommentar.

Macht ihr das von Hand, gilt dieselbe Regel. Schließt den Loop nicht vom Pull Request aus. Schließt ihn vom veröffentlichten Eintrag aus, und schließt ihn einmal. Feed und Widget tragen denselben Eintrag an alle, die nicht gefragt haben, was die meisten sind; der Kommentar ist für die, die gefragt haben.

Warum die meisten Feature-Request-Vorlagen scheitern

Sie sind darauf ausgelegt, die Triage zu erleichtern, und das gelingt ihnen, auf Kosten des einzigen Moments, der der anfragenden Person wichtig ist. Eine Vorlage mit zwölf Feldern bekommt weniger Anfragen, und die, die sie bekommt, stammen von Leuten mit der Geduld, zwölf Felder auszufüllen, was nicht dieselbe Gruppe ist wie die, die das Feature brauchen. Eine Vorlage mit vier Feldern, von denen eines “wie erreichen wir dich” ist, bekommt mehr Anfragen und kann jede davon würdigen.

FAQ

Sollte eine Feature-Request-Vorlage nach Priorität fragen? Nein. Fragt stattdessen nach dem Workaround. “Ich exportiere in eine Tabelle und tippe es jeden Freitag neu ein” sagt mehr über Priorität als ein Dropdown, das die einreichende Person auf hoch gesetzt hat.

Sollten anfragende Personen einen Lösungsweg vorschlagen? Sie können, im Freitext. Macht es nicht zur Rahmung. Als Lösungen formulierte Anfragen sind schwerer miteinander zusammenzuführen und schwerer, einen Changelog-Eintrag darüber zu schreiben.

Sollten Feature-Anfragen auf einer öffentlichen Roadmap erscheinen? Sobald sie geplant sind, ja: Ein Label auf demselben Issue setzt es in die Spalte “Geplant”, und die anfragende Person kann zusehen, wie es sich bewegt. Der Artikel Öffentliche Roadmap ist der Mechanismus.

Wie gehe ich mit Duplikaten um? Verlinkt die neue Anfrage mit dem bestehenden Issue und labelt sie niedrige Priorität; schließt sie nicht. Jedes Duplikat ist eine weitere Person, der bei Auslieferung Bescheid zu geben ist. Mit dem automatischen Kommentar von changeloop erfährt diese Person es nur, wenn der Pull Request auch ihr Issue nennt (Fixes #142, fixes #187).

Wo sollte die Vorlage liegen? Im Repository, das den Pull Request erhalten wird, damit das Schließ-Schlüsselwort funktioniert. Eine Anfrage in einem separaten Tracker muss beim Merge von Hand verlinkt werden, und genau dieser Schritt wird übersprungen.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Entwicklerdokumentation, Changelog-Tools im Vergleich