Feature Requests vs. Bug Reports: Den Unterschied kennen

In der wissenschaftlichen und Engineering-Software kommt die größte Frustration nicht von schwierigen Problemen – es kommt von unklaren Problemaussagen. Ein Ticket, das „falsch klingt“, könnte tatsächlich eine fehlende Fähigkeit beschreiben. Eine Anfrage nach einer „kleinen Verbesserung“ könnte darin bestehen, einen Defekt zu maskieren, der die Ergebnisse beschädigt. Wenn Teams Tickets falsch klassifizieren, verschwenden sie Zeit: Entwickler untersuchen Phantomfehler, Forscher warten auf Features, die nie im Ziel waren, und Prioritäten driften.

Dieser Leitfaden hilft Ihnen dabei, schnell zu entscheiden, ob es sich um einen Fehlerbericht oder eine Feature-Anfrage handelt, und zeigt, wie Sie jeden einzelnen schreiben, damit das Team darauf reagieren kann. Das Ziel ist einfach: weniger Hin- und Her-Kommentare, schnellere Triage und weniger Überraschungen bei Veröffentlichungen.

Warum die Unterscheidung wichtig ist

Fehlerberichte und Funktionsanforderungen werden in den meisten Workflows (TRAC, JIRA, GitHub Issues, Redmine usw.) unterschiedlich behandelt. Sie haben unterschiedliche Dringlichkeit, unterschiedliche Akzeptanzkriterien und verschiedene Möglichkeiten, die Schleife zu testen und zu schließen.

• Ein Fehlerbericht hat normalerweise die Erwartung der Richtigkeit: Die Software verstößt gegen ihren eigenen Vertrag, ihre Dokumentation oder ihr etabliertes Verhalten.
• Eine Feature-Anfrage fragt nach neuem Verhalten: etwas, was die Software derzeit nicht verspricht, auch wenn es nützlich wäre.

Wenn Sie das Ticket richtig beschriften, wird die Triage einfacher: Betreuer können reproduzieren, priorisieren und Arbeiten zuweisen, ohne zu erraten, was „soll“ passieren sollte.

Die Kerndefinitionen

Was ist ein Fehlerbericht?

Ein Fehler ist, wenn sich das System im Vergleich zu einem vereinbarten Referenzpunkt falsch verhält. Dieser Bezugspunkt kann sein:

• Dokumentation oder eine veröffentlichte Schnittstelle (API-Vertrag)
• Vorheriges stabiles Verhalten (eine Regression)
• Wissenschaftliche Korrektheit (z. B. Erhaltungsgesetze, erwartete Invarianten, Einheitskonsistenz)
• klar angegebene Anforderungen (einschließlich Tests oder Spezifikationen)

Kurz gesagt: Ein Fehlerbericht beschreibt einen Fehler, der behoben werden sollte, um die Korrektheit wiederherzustellen.

Was ist eine Funktionsanfrage?

Eine Feature-Anforderung schlägt eine Fähigkeit oder Verbesserung vor, die das System nützlicher, flexibler oder effizienter machen würde, aber nicht für die Richtigkeit des aktuellen Verhaltens erforderlich ist. Beispiele sind:

• Unterstützt einen neuen Randbedingungstyp
• Hinzufügen eines Exporters für ein neues Dateiformat
• Die Leistung über die aktuellen Ziele hinaus verbessern
• Hinzufügen von UI/CLI-Optionen, die noch nicht vorhanden sind

Kurz gesagt: Eine Funktionsanforderung beschreibt etwas Neues, das das System tun sollte.

Schnelle Entscheidungs-Checkliste

Wenn Sie sich nur an eine Regel erinnern, verwenden Sie diese:

• Wenn die Software ein Versprechen bricht, ist es ein Fehler.
• Wenn Sie ein neues Versprechen wünschen, ist es eine Funktion.

Stellen Sie sich diese Fragen:

1. Hat es jemals zuvor im selben Szenario funktioniert? Wenn ja, wahrscheinlich ein Fehler (möglicherweise eine Regression).
2. Gibt es eine Dokumentation, die besagt, dass das Verhalten funktionieren sollte? Wenn ja, Bug.
3. Ist das Verhalten mehrdeutig und Sie schlagen vor, was es sein sollte? wahrscheinlich ein Feature (oder zuerst eine Spezifikationsklärung).
4. Ist das Problem, dass Sie überhaupt nichts tun können, aber nichts ist mit vorhandenen Ausgaben „falsch“? wahrscheinlich eine Funktion.
5. Erzeugt es falsche Ergebnisse, Abstürze, beschädigte Daten oder verstößt gegen physische Einschränkungen? Käfer

Side-by-Side-Vergleich

Beispiele im wissenschaftlichen Rechnen

Beispiel 1: Falsche Ergebnisse aufgrund von Unstimmigkeiten der Einheiten

Sie führen eine Simulation durch und bemerken, dass ein als „Meter“ dokumentierter Parameter als „Millimetern“ behandelt wird und die Ergebnisse um das 1000× verschiebt. Wenn Dokumentation und Code nicht übereinstimmen und die Ausgaben für die dokumentierte Verwendung falsch sind, ist dies ein Fehlerbericht. Ihr Ticket sollte den Parameter enthalten, in dem es dokumentiert ist, ein minimaler Fall und ein Hinweis auf eine Nichtübereinstimmung.

Beispiel 2: Benötigen Sie einen neuen PDE-Term oder eine neue Kopplung

Sie möchten einem vorhandenen Transportmodell einen Elektromigrationsbegriff hinzufügen. Der aktuelle Code funktioniert wie geplant; Es enthält nur diese Physik. Das ist eine Feature-Anfrage. Ihr Ticket sollte die maßgebliche Gleichung, die erwarteten Eingaben und die Validierung (Benchmarks oder analytical limits) erläutern.

Beispiel 3: „Es ist zu langsam“

Leistung kann entweder sein. Wenn der Code in 5 Minuten ausgeführt wird und jetzt 50 Minuten für das gleiche Setup dauert, ist dies ein Fehler (eine Leistungsregression). Wenn der Code immer 50 Minuten gedauert hat und Sie möchten, dass er 5 dauert, ist dies eine Feature-Anfrage (Optimierungsarbeit), es sei denn, die Langsamkeit beruht auf einem unbeabsichtigten Verhalten (wie ein Solver, der aufgrund eines Konvergenzproblems feststeckt).

Beispiel 4: Verwirrende Fehlermeldung

Eine verwirrende Fehlermeldung ist in der Regel eine Feature-Anforderung (Verbessern Sie UX), es sei denn, die Nachricht ist sachlich falsch oder maskiert den realen Fehler auf eine Weise, die die Diagnose verhindert. In vielen Teams wird die „Fehlermeldung verbessern“ als Verbesserung und nicht als Fehler verfolgt.

Häufige Fehlklassifizierungen und wie man sie behebt

Fehlklassifizierung: „Es stürzt ab“ (aber nur mit ungültiger Eingabe)

Wenn die Software bei ungültigen Eingaben abstürzt, kann dies ein Fehler sein, wenn das Programm ordnungsgemäß ausfallen sollte (Fehler löschen, keine beschädigten Dateien). Wenn ein Absturz erwartet wird, da die Eingabe außerhalb der unterstützten Einschränkungen liegt und das Tool dies bereits dokumentiert, kann dies eine Verbesserungsanforderung sein, um die Validierung und das Messaging zu verbessern.

Fehlklassifizierung: „Die Ausgabe sieht falsch aus“ (aber die Erwartungen sind unklar)

Wenn das Ticket nicht definiert, was „richtig“ bedeutet, können die Betreuer Bug vs. Feature nicht entscheiden. Schreiben Sie in diesem Fall das Ticket als Frage plus eine vorgeschlagene Erwartung und fügen Sie Beweise bei. Oft ist der beste erste Schritt: „Erwartetes Verhalten klären“ – dann als Fehler oder Feature erneut einreichen, sobald bestätigt.

Fehlklassifizierung: „Bitte Option X hinzufügen“ (der Code unterstützt sie bereits)

Dies ist weder eine Funktion noch ein Fehler im Kernverhalten – es kann eine Dokumentationslücke sein. Wenn die Fähigkeit vorhanden ist, aber nur schwer zu finden ist, erstellen Sie ein Doc-Ticket (oder eine Verbesserung, die sich auf die Benutzerfreundlichkeit konzentriert).

So schreiben Sie einen hochwertigen Fehlerbericht

Ein guter Fehlerbericht erleichtert das Reproduzieren, Diagnostizieren und Verifizieren der Korrektur.

Fehlerbericht-Vorlage

• Zusammenfassung: Ein Satz beschreibt das falsche Verhalten
• Umgebung: OS, Python/C++-Version, Paketversion/Commit, MPI/Solver-Versionen ggf.
• Schritte zum Reproduzieren: Minimale Schritte, minimale Eingabedateien, minimaler Code-Snippet
• Erwartetes Ergebnis: Was sollte passieren und warum (Dokumente / Tests / vorheriges Verhalten)
• Tatsächliches Ergebnis: Was passiert stattdessen (Protokolle, Stapelverfolgung, Screenshots, Ausgabediff)
• Auswirkung: Schweregrad (Absturz, falsche Wissenschaft, geringe Benutzeroberfläche), Häufigkeit, Problemumgehung, falls vorhanden

Beispiel eines Fehlerberichts (kurz)

Zusammenfassung: Diffusionsbeispiel schlägt mit Dirichlet BC im 3D-Raster fehl.

• Erwartet: Simulation läuft und erzeugt stabile Feldwerte wie in 2D.
• Tatsächlich: Solver divergiert nach n Schritten; Werte werden zu Nan.
• Evidenz: Geben Sie minimale Skripte, Parameterwerte und Protokollausgaben an.

So schreiben Sie eine starke Feature-Anfrage

Eine starke Feature-Anfrage liest sich wie ein Mini-Design HINWEIS: Sie erklärt, warum die Funktion wichtig ist, wie „erledigt“ aussieht und wie Sie sie überprüfen.

Feature-Anforderungsvorlage

• Problemstellung: Was Sie heute nicht tun können
• Anwendungsfall: Wer braucht es und warum (Forschungsworkflow, Lehrmodul, Produktionspipeline)
• Lösungsvorschlag: Verhalten auf hoher Ebene, Änderungen an der Benutzeroberfläche/API, Standardeinstellungen
• Akzeptanzkriterien: Was muss wahr sein, um es vollständig zu betrachten?
• Validierung: Testen (Benchmarks, Unit-Tests, Analyselösungen, Regressions-Suite)
• Alternativen betrachtet: Problemumgehungen oder andere Ansätze

Beispiel für Feature-Anforderung (kurz)

Anfrage: Fügen Sie eine Option zum Exportieren des Simulationsstatus in ein standardisiertes Visualisierungsformat in konfigurierbaren Intervallen hinzu.

• Anwendungsfall: Große Läufe auf HPC, bei denen eine Zwischenvisualisierung für die Überwachung erforderlich ist.
• Akzeptanz: Export funktioniert für 2D/3D-Raster; Enthält Metadaten (Zeitschritt, Einheiten); Keine größere Verlangsamung.
• Validierung: Vergleichen Sie exportierte Felder mit Arrays im Arbeitsspeicher; Stellen Sie sicher, dass das Nachladen den Zustand innerhalb der Toleranz wiedergibt.

Wenn ein Ticket zwei werden sollte

Viele reale Probleme mischen Fehler und Funktionen. Das Teilen beschleunigt oft den Fortschritt.

• Wenn es einen Absturz (Bug) und auch den Wunsch nach einer netteren Nachricht (Feature) gibt, reichen Sie zwei Tickets ein.
• Wenn es ein Problem mit der Korrektheit (Bug) und auch eine Anfrage zur Unterstützung eines neuen Regimes gibt, trennen Sie das „Aktuelle Verhalten“ von der „Erweiterungsfähigkeit“.
• Wenn die Anfrage „schneller“ ist, aber Sie vermuten, dass Sie eine Regression vermuten, legen Sie einen Fehler für die Regression und eine Funktion zur weiteren Optimierung ein.

Durch das Teilen von Tickets können Teams den Fehler schnell schließen und die Verbesserung sinnvoll planen.

Triage-Tipps für Betreuer und Leads

Verwenden Sie Etiketten und einen kurzen Entscheidungskommentar

Wenn ein Ticket mehrdeutig ankommt, fügen Sie einen kurzen Kommentar hinzu, der die Klassifizierung sperrt:

• „Als Fehler klassifizieren, weil Verhalten dem Dokumentationsabschnitt X widerspricht.“
• „Klassifizierung als Feature-Anforderung, da dadurch neue Solverfunktionen hinzugefügt werden, die derzeit nicht unterstützt werden.“

erfordern minimale Akzeptanzkriterien für Funktionen

Feature-Anfragen scheitern, wenn „Fertig“ unklar ist. Fragen Sie früh nach Akzeptanzkriterien: Welche Ausgabe, welche Schnittstelle, welche Tests, welches Beispiel. Ein Feature ohne Akzeptanzkriterien ist effektiv ein Wunschlistenelement.

Verwandeln Sie wiederkehrende Fragen in Dokumentationsaufgaben

Wenn mehrere „Feature-Anfragen“ tatsächlich Anleitungsanfragen sind („Wie mache ich…?“), Erfassen Sie diese als Dokumentenverbesserungen. Dies ist insbesondere in wissenschaftlichen Bibliotheken üblich, in denen Fähigkeiten vorhanden sind, die jedoch nicht offensichtlich sind.

Praktische Vorlagen, die Sie in Tickets kopieren können

Einzeiler-Klassifikator

Verwenden Sie dies als erste Zeile Ihrer Ticketbeschreibung:

• BUG: „Beobachtetes Verhalten widerspricht dem erwarteten Verhalten von [docs/test/previous version].“
• Feature: „Neue Funktion zur Unterstützung von [use case] erforderlich, derzeit nicht verfügbar.“

Akzeptanzkriterien Starterset für Features

• API: Neue Option/Parameter mit Standardeinstellungen dokumentiert
• Beispiel: Minimales Arbeitsbeispiel in Dokumenten/Beispielen
• Tests: Mindestens ein automatisierter Test deckt das Hauptverhalten ab
• Rückwärtskompatibilität: Vorhandene Skripte laufen unverändert weiter (oder Migrationsschritte dokumentiert)

Schlussfolgerung

Fehlerberichte stellen das Vertrauen wieder her; Feature-Anfragen erweitern die Fähigkeit. Beide sind in wissenschaftlicher Software unerlässlich, aber sie sind nur erfolgreich, wenn sie mit der richtigen Absicht und Beweisen geschrieben werden. Wenn Sie Fehler an einen Referenzpunkt verknüpfen und Funktionen an einen klaren Anwendungsfall mit Akzeptanzkriterien binden, reduzieren Sie die Triage-Reibung, beschleunigen die Entwicklung und machen Releases vorhersehbarer – was letztendlich die Forschungsgeschwindigkeit und die Zuverlässigkeit der Ergebnisse verbessert.