Warum kann das Zitieren von Fehler-IDs in Patchnotizen als schlechte Praxis angesehen werden?

Basierend auf einem Kommentar und nachfolgenden Upvotes von Bug Reopen vs. New :

Das Zitieren von Fehler-IDs in Patchnotizen ist nur ... sehr unfreundlich. - Krelp

Es scheint, dass zumindest einige Leute der Meinung sind, dass es keine gute Idee ist, auf Fehler-IDs in Patchnotizen zu verweisen. Ich bin ein ziemlich unerfahrener Entwickler und frage mich, warum das so ist.

Meiner Meinung nach ist dies eine gute Vorgehensweise, vorausgesetzt, Ihre Benutzer haben Lesezugriff auf Ihre Bug-Datenbank. Es gibt viele Male, in denen die Leute auf einen bestimmten Fehler warten, der behoben werden muss, um zu entscheiden, wann ein Upgrade durchgeführt werden soll.

Ich denke, was verpönt ist, ist nur die Fehler-ID und sonst nichts zu zitieren. Sie sollten immer auch eine Beschreibung angeben, die verständlich ist, ohne den Bug-Tracker aufzurufen. Auf diese Weise können Sie auch in Zukunft den Bug-Tracker wechseln, ohne Ihre vorherigen Versionshinweise gänzlich ungültig zu machen.

Es ist, wie in dem zitierten Kommentar gesagt, ... unfreundlich.

Unfreundlich mit dir

Stellen Sie sich das folgende Szenario vor. Sie zeigen die Protokolle in der Quellcodeverwaltung an. Sie fragen sich, was sich für ein Commit geändert hat. Anstatt es im Klartext zu erklären, heißt es:

# 1307 gelöst

Sie führen das Bug-Tracking-System in der Hoffnung, etwas Hilfreiches zu haben. Bug # 1307 wird als behoben gemeldet. In der Beschreibung sehen Sie:

Gleicher Bug wie # 1284

Danke, es ist sehr hilfreich. Sie müssen jetzt zu Fehlerbericht Nr. 1284 navigieren, um zu lesen, dass es sich um ein Duplikat von Fehler Nr. 1113 handelt, der sich auf die Fehler Nr. 1112, Nr. 1065 und Nr. 1067 bezieht.

Fünf Minuten später haben Sie keine Ahnung, wonach Sie zu Beginn suchen.

Eine viel hilfreichere Protokollmeldung zur Versionskontrolle wäre:

Es wurde ein Problem behoben, bei dem sich Benutzer nicht mit einem Kennwort anmelden konnten, das länger als 25 Zeichen war (siehe Nr. 1307), indem auf die Datenzugriffsebene dieselbe Kennwortlängenrichtlinie wie auf der Website selbst angewendet wurde.

Auf die gleiche Weise könnte der Bericht Nr. 1307 im Fehlerverfolgungssystem selbsterklärender sein und sich daran erinnern, worum es in dem Fehlerbericht Nr. 1284 ging und wie sich der neue von dem alten unterscheidet.

Unfreundlich mit Kunden

Dies ist nicht die einzige Frage der Freundlichkeit.

Ein zweiter Grund ist, dass Sie durch zu viele Verweise ohne zusätzliche Informationen die Berichte zu Patchnotizen, Versionskontrollprotokollen und Fehlerverfolgungssystemen für Personen unbrauchbar machen, die mit diesen Systemen nicht sehr vertraut sind . Wenn Sie sich täglich mit einem Fehlerverfolgungssystem beschäftigen, können Sie schnell durch die Berichte navigieren, mehrere Berichte nebeneinander anzeigen usw. Wenn Sie ein Kunde ohne technischen Hintergrund sind, können Sie leicht verloren gehen.

Auch hier sind detailliertere Nachrichten sehr hilfreich als nur eine Referenz. Beachten Sie, dass Sie weiterhin Verweise behalten möchten: Nichts ist schlimmer als ein Fehler, der mit dem vor zwei Wochen aufgetretenen Fehler identisch ist, aber Sie können sich nicht an seine ID erinnern.

In vielen Ländern besteht das gleiche Problem. In Frankreich ist es beispielsweise nicht ungewöhnlich, dass eine Gesetzgebung auf mehrere Quellen verweist, die sich inzwischen ändern können. Das bedeutet, dass Sie, um es vollständig zu verstehen, manchmal Stunden in einer Bibliothek verbringen müssen, um nach Dutzenden von verwiesenen Texten zu suchen, wobei jeder Text seine eigenen Verweise auf andere hat.

Das Zitieren von Ausgabenummern in Patchnotizen ist nichts Falsches, vorausgesetzt, Benutzer können die zitierte Ausgabe lesen. Wenn Ihre Bug-Datenbank es jedem erlaubt zu lesen, kann das Zitieren der Bug-Nummer in der Tat sehr nützlich sein. (Wenn Ihre Patchnotizen in einem Format vorliegen, das Verknüpfungen zulässt, machen Sie diese Problem-IDs zu Verknüpfungen zu dem betreffenden Problem.) Dies bedeutet nicht, dass Sie alle Probleme der Öffentlichkeit zugänglich machen sollten. Es kann immer noch nützlich sein, solche zu haben, die versteckt sind (z. B. wo sie Live-Passwörter haben!)

Es ist ziemlich unfreundlich, eine Ausgabenummer zu nennen, bei der der Leser nicht nach Details und Verlauf des Fehlers suchen kann. Nicht, dass das Zitieren solcher Probleme ohne die Problem-ID viel freundlicher ist.

Es hängt natürlich davon ab, wer die Personen sind, die die Patchnotizen lesen, und von den Zielbenutzern der Software.

In den meisten Fällen kümmert sich die große Mehrheit Ihrer Benutzer jedoch nicht darum, wie die Fehler-ID lautet. Es ist ihnen egal, warum es kaputt war, was das Problem ist oder sonst etwas - sie möchten nur wissen, was sich mit einer sehr knappen Textbeschreibung geändert hat, ohne bei jeder Änderung auf eine andere Seite wechseln zu müssen.

Das Zitieren der Fehler-IDs lässt mich innehalten und nachdenken, und ich - als Benutzer - möchte nicht nachdenken. Es ist eine Art Usability-Problem.

Schauen Sie sich beispielsweise das Änderungsprotokoll von Visual Assist X an . Alle diese verknüpften Fehler-IDs sind nur Rauschen, das mich vom Verständnis der Änderungen ablenkt. Und dies ist ein Add-On für ein Visual Studio, das sich an Programmierer richtet. Und ich bin ein Programmierer. Wenn mich das stört, stellen Sie sich den durchschnittlichen Benutzer vor, der nicht einmal weiß, was ein Bug-Tracker ist.

PS: Ich war der Autor des Kommentars, der die Frage ausgelöst hat

Eine Bug-ID ist für einen Referenzpunkt obligatorisch . Die Gründe:

• Verhindern Sie Mehrdeutigkeiten: Zwei oder mehr Fehler haben möglicherweise ähnliche Beschreibungen. Man würde also einen Anker brauchen, um zwischen ihnen zu unterscheiden.
• Bequemlichkeit : Bei der Besprechung eines Fehlers, entweder mit einem Kunden oder intern, wird die Fehler-ID häufig als Kurzform verwendet. Wenn die ID in den Patchnotizen weggelassen wird, ist es schwierig, darüber zu diskutieren:

3052 wurde bereits behoben und arbeitet noch an 3077

ist bequemer als:

Der "Absturz der Anwendung beim Anwenden" wurde behoben und die "NullReferenceException beim Klicken auf Benutzer wechseln" wurde noch ausgeführt.

Ich würde sagen, dass es von Ihrem System abhängt: Ich bin glücklich, dass derjenige , den ich verwende, solche Verweise in Commit-Nachrichten automatisch erkennt und einen Link zu dem im Bug-Tracker gespeicherten Ticket hinzufügt , so dass es kein Problem ist.

Aber wenn ich auf einem System wäre, auf dem es nicht verfügbar ist, würde ich immer noch die Ticket-ID erwähnen (auf diese Weise können Sie Protokolle schnell anhand der Ticket-ID durchsuchen ) sowie eine kurze Beschreibung des Fehlers.