Bug Best Practices

Bug Tracking Best Practices

Warum

Obwohl eigentlich einleuchtend und selbstverständlich haben “ordentliche” Bug-Tracking best practices eine Reihe entscheidender Vorteile:

• Transparenz: Alle Mitarbeiter haben einen genauen Überblick über den Stand des Projekts / der einzelnen Komponenten
• Milestones und wesentliche Entwicklungsschritte über Komponenten hinweg können besser erreicht werden, das gesamte Projekt sich schneller entwickeln
• Genauigkeit: Durch die Transparenz und das Wegfallen von “Flüsterpost-Ketten” ist es wesentlich einfacher sich gemeinsam zu koordinieren
• Genaue Rückgabe: Es ist zu jedem Zeitpunkt klar, was man den Philsophen gegenüber geliefert hat / was noch aussteht / wer gerade woran arbeitet.
• Vererbbarkeit: Wenn sich die Zusammensetzung der Teams ändert, können nachfolgende Entwickler sich schnell und klar einen Überblick über die ausstehenden Probleme und bisherigen Lösungen verschaffen.

Wie

Im folgenden eine Beschreibung der Konventionen und Vorgänge, wie bugs gehandhabt werden sollen.

Konventionen

Bugs sollen ordentlich dokumentiert werden und getagged werden.

Taggen erlaubt es, die offenen bugs zu sortieren, filtern und damit besser im Überblick behalten zu können.

Ordentlich dokumentieren bedeutet, dass ein nachfolgender genau nachvollziehen kann, wie/wann/wer mit einem Bug umgegangen wurde.

Dazu gehören:

• taggen: priorisieren (siehe unten, Prioritäten)
• taggen: Status (siehe unten, Workflow)
• dokumentieren: Wenn sich der Status eines Bugs ändert, am besten einen Kommentar im Bug-Verlauf hinterlassen, am besten so:
  • Beispiel: [Issued -> Analyze]. Dies würde bedeuten, dass sich Person Foo mit dem Bug auseinandersetzt und den tag Issued entfernt und durch den tag Analyze ersetzt hat. Dies bedeutet für alle anderen, dass:
    • sich bereits jemand um den Bug kümmert
    • andere können die noch offenen bugs bequem filtern und sehen, was als nächstes zu tun ist
  • Beispiel: [p1 -> p2].
    • Bedeutet: Person Foo hat den Bug herunterpriorisiert von P1 nach P2
  • Beispiel: [+p1]
    • Bedeutet: Person hat P1-tag an den Bug hinzugefügt

Prioritäten

Bugs sind am besten Priorisiert von “P1” bis “P4”.

Die Prioritäten entsprechen ungefähr folgenden Ideen:

• P1: Showstopper. Muss sofort behoben werden. Kritischer Bug.
• P2: Wichtiger Bug. Sollte ebenfalls schnellstmöglich behoben werden. Wichtiger Bug.
• P3: Durchaus wichtiger Bug, aber nicht unbedingt wesentlich solange noch P1 und P2 Bugs vorliegen. Können auch Feature Requests sein, die dann zumeist zu P4-Bugs werden.
• P4: Nicht so wichtiger Bug. Meist “Nice To Have” Feature Requests oder wird häufig vergeben für “Next Release/Milestone”, d.h. dieses Feature wird wohl erst im nächsten Milestone umgesetzt werden.

Workflow

Der Workflow orientiert sich an folgendem Modell: Der Bug geht durch verschiedene Phasen, die unterschiedliche Bedeutung haben. Diese werden immer per tag signalisiert. So können andere ablesen, dass jemand an einem bug arbeitet. Die Phasen und ihre Bedeutungen sind folgende:

• status:issued ---> der bug wurde eröffnet/angelegt (und ist womöglich noch nicht einmal an jemanden assigned)
• status:analyze ---> der assignee arbeitet an der Lösung des Bugs
• status:fixed ---> der assignee setzt den bug auf fixed, wenn er die Lösung eingecheckt hat
• status:review ---> der assignee kann an jemand anderen assignen, der eine code-review durchführen soll und setzt den bug auf 'status:review'
• status:verify ---> der reviewer schickt den bug an den originator zum verify-en: hierbei kommt dem Ersteller des bugs die Aufgabe zu, zu entscheiden, ob der Bug in seinem Interesse gelöst wurde. Wenn ja, dann geht der Bug in den nächsten Status: 'status:closed', wenn nein, geht der bug wieder in Phase 1: 'status:issued' zurück, und das Spiel beginnt von vorne, bis der bug vom Originator als zufriendestellend gelöst ge-'closed' werden kann.
• status:closed

Spezialität: Umbrella-Bug

Wenn es mehrere "related" Bugs zu einem größeren Thema gibt, so bietet es sich an einen umbrella-Bug zu definieren, der alle diese verstreuten, kleineren Bugs zusammenfasst und miteinander referenziert.

Die wird am Einfachsten so gehandhabt, dass:

• der umbrella-Bug bekommt einen tag 'umbrella'
• der umbrella bug bekommt eine Bezeichnung/Beschreibung 'umbrella bug'
• der umbrella bug referenziert die die related-bugs, indem er tags bekommt mit den bug-id's der related bugs, also, z.B. '#19, #22, #53'. Damit wäre klar, dass der umbrella-bug die bugs mit den Nummern 19, 22 und 53 zusammenfasst
• Wenn man in der Beschreibung des Umbrella Bugs eine kleien Beschreibung anlegt, die sagt 'this is an umbrella bug for bugs #19, #22, #53', so wird in den referenzierten Bugs dieses automatisch von gitlab eingetragen: 'this bug was mentioned in bug XY'. Dies ist ziemlich praktisch.

Szenarien

1. Externe Person öffnet Bug (Issued)
2. Jemand bearbeitet den bug (Analyze)
3. Maintainer macht den Fix (Fixed)
4. Anderer Maintainer macht review (Review)
5. Bug wird an den Originator zurückgeschickt (Verify)
   1. Originator leht ab: zurück auf 1.
   2. Originator akzeptiert: Closed

Git Best Practices

siehe auch: Git Best Practices