Wie sollten Versionshinweise verfasst werden?

Question

Gibt es eine Art Leitfaden oder bewährte Verfahren, wie Versionshinweise geschrieben werden sollten? Ich denke, ich versuche, das richtige Gleichgewicht zu finden, ohne zu spezifisch zu sein. Stellen die Entwickler in der Regel mehr Versionshinweise für das QA-Team zur Verfügung als die, die für die Öffentlichkeit bestimmt sind?

Answer 1

Öffentliche Freigabemitteilungen sollten mindestens enthalten:

• Freigabe, Build-Nummer
• alle behobenen öffentlichen Fehler
• alle zusätzlichen öffentlichen Funktionen

QA Release Notes sollten mindestens enthalten:

• Freigabe, Buildnummer
• alle behobenen Fehler einschließlich Fehlernummer
• alle hinzugefügten Funktionen einschließlich Links zu Entwurfsdokumenten

Denken Sie an Ihre Zielgruppe und versuchen Sie, sich vorzustellen, was sie braucht.

Ein weiterer Punkt ist die neue oder nicht mehr vorhandene Unterstützung für bestimmte Plattformen. (Zum Beispiel haben wir die Unterstützung für Win3.1 eingestellt und Vista 64 Bit hinzugefügt).

Answer 2

Ich würde einen Blick in die Versionshinweise beliebter F/OSS-Projekte werfen:

• Firefox
• GIMP
• Ubuntu
• Android
• TeamCity
• usw.

Alle diese Projekte haben recht lesbare und ausgewogene Versionshinweise.

Answer 3

Wenn Sie ein System zur Projektverwaltung/Problemverfolgung haben, sollten Sie dieses auf jeden Fall für die Erstellung Ihrer Versionshinweise verwenden. Trac y Redmine sind in dieser Hinsicht besonders gut.

Freisetzungspunkte sollten einige Eigenschaften haben, IMO:

• Denken Sie an Ihr Publikum. Wenn es sich um eine iPhone-App handelt, werden sich nur wenige für die Tatsache interessieren, dass ein bestimmter Logikfehler in Zeile 572 in der Foo-Klasse behoben wurde. Aber sie werden sich sehr dafür interessieren, dass die App jetzt beschleunigungssensitiv ist.
• Fassen Sie die neuen Entwicklungen, Funktionen und Fehlerbehebungen nach Möglichkeit in einem großen, umfassenden Überblick zusammen. Wenn Sie diese thematisch miteinander verbinden können (z.B. "wir haben generische und anonyme Typen implementiert"), ist ein kurzer Text darüber ein guter Weg, um den Leuten das Gesamtbild zu vermitteln.
• Nennen Sie die spezifischen Dinge, die behoben wurden, mit Links zu Ihrem öffentlichen Bug-Tracker, falls vorhanden. Dies kann normalerweise automatisch erstellt werden.
• Geben Sie keine unerträglichen Details an. Eine ein- oder zweizeilige Zusammenfassung jedes hinzugefügten oder behobenen Problems sollte ausreichen.
• Geben Sie gegebenenfalls immer spezifische Versionsbezeichnungen an (z. B. "v.1.4.5").

Answer 4

Das hängt wirklich vom Publikum ab. Für technische Benutzer (z. B. Entwickler, die Ihre API verwenden) können Sie sehr technisch sein. Auf der anderen Seite sind die anspruchsvollen Endnutzer einer von Ihnen erstellten Anwendung vielleicht nur an neuen Funktionen und größeren Änderungen interessiert.

Dazwischen gibt es nicht-technische Benutzer, die die Details ebenfalls benötigen, z. B. die Support-Abteilung. Für diese Personen können Sie eine detaillierte Beschreibung ohne die technischen Details geben, z. B. "Es wurde ein Fehler behoben, bei dem der Datensatz nicht in der Datenbank gespeichert wurde".

Answer 5

Ein bewährtes Verfahren für Versionshinweise ist meiner Meinung nach die Automatisierung. Wenn es bestimmte Best Practices für die Übermittlung von Meldungen des Revisionskontrollsystems gibt ( http://drupal.org/node/52287 ), können Sie Versionshinweise durch ein automatisiertes Skript erstellen ( http://cvs.drupal.org/viewvc.py/drupal/contributions/tricks/cvs-release-notes/ ). Dies würde sehr schöne Versionshinweise ergeben: http://drupal.org/node/226165