Pull-Request-Kommentare in Release Notes hinzufügen

ChatGPT:

Wenn der Release Drafter den Body-Text mehrerer Pull Requests zusammenführt, tut er dies auf eine strukturierte Weise basierend auf den Konfigurationen in deiner release-drafter-config.yml Datei. Hier ist eine Erklärung, wie dieser Prozess funktioniert und wie du sicherstellen kannst, dass die zusammengeführten Informationen klar und effektiv präsentiert werden:

Zusammenführung von Pull Request Informationen durch Release Drafter

Kategorisierung: Release Drafter kann Pull Requests basierend auf Labels in verschiedene Kategorien einteilen. Jedes Label kann einer spezifischen Kategorie zugeordnet werden, und der Release Drafter fügt alle PRs, die unter ein bestimmtes Label fallen, in der entsprechenden Kategorie in den Release Notes zusammen.

Beispiel für eine Kategorisierung in release-drafter-config.yml:
```
categories:
 - title: 'Features'
   labels:
     - 'feature'
 - title: 'Bug Fixes'
   labels:
     - 'bug'
```
In diesem Beispiel werden alle PRs, die mit "feature" gelabelt sind, unter der Überschrift "Features" und alle mit "bug" unter "Bug Fixes" zusammengefasst.
Template-Struktur: Du kannst die Struktur der Release Notes durch das Template im Release Drafter definieren. Dieses Template bestimmt, wie die Informationen aus den Pull Requests dargestellt werden. Du kannst festlegen, Titel und Body der PRs zu verwenden, und wie sie innerhalb jeder Kategorie angezeigt werden sollen.

Beispiel für eine Template-Struktur:
```
template: |
 ## What's Changed
 $CHANGES

 ## Full Changelog: $FULL_HISTORY
```
Hier wird $CHANGES durch eine Zusammenfassung der Änderungen ersetzt, die aus den Titeln und Beschreibungen der PRs stammen, die seit dem letzten Release gemerged wurden.
Versions- und Tag-Handling: Release Drafter kann auch die Versionsnummern und Tags verwalten, die zu jedem Release gehören. Die Versionsnummer kann basierend auf den Typen von Änderungen automatisch erhöht werden, und der Tag wird entsprechend angepasst.
Aggregation der Details: Für den Body-Text der PRs nimmt Release Drafter standardmäßig den gesamten Text auf. Wenn du eine spezielle Formatierung oder spezifische Informationen aus dem PR-Body hervorheben möchtest, musst du die PRs entsprechend strukturieren. Der Release Drafter wird sie dann einfach nacheinander unter der entsprechenden Kategorie auflisten.

Best Practices für effektive Release Notes

Klare Kommunikation: Stelle sicher, dass alle Beteiligten verstehen, wie ihre PRs für die Release Notes formatiert sein sollten. Dies kann durch Richtlinien oder Templates erreicht werden.
Nutzung von Labels: Die effektive Nutzung von Labels hilft, die Informationen in den Release Notes sinnvoll zu organisieren und sicherzustellen, dass ähnliche Änderungen zusammengefasst werden.
Regelmäßige Überprüfung: Es kann hilfreich sein, die generierten Release Notes vor der Veröffentlichung zu überprüfen, um sicherzustellen, dass sie die relevanten Informationen korrekt und klar darstellen.

Der Release Drafter ist ein mächtiges Tool, das dir hilft, den Überblick über wichtige Änderungen zu behalten und die Kommunikation über neue Features und Bugfixes in deinen Projekten zu verbessern.

Kannnst du mir ein Beispiel zeigen?

PR1:

Titel: "Feature A"
Body: "Das Feature A ist sehr gut"

PR2:

Titel: "Feature B"
Body: "Das Feature B eröffnet neue Möglichkeiten"

Um zu veranschaulichen, wie der Release Drafter die Informationen aus den Pull Requests (PRs) wie den von dir beschriebenen zusammenführt, schauen wir uns ein konkretes Beispiel an. Nehmen wir an, du hast deine release-drafter-config.yml Datei wie folgt konfiguriert:

Beispielkonfiguration in `release-drafter-config.yml`

name-template: 'v$NEXT_PATCH_VERSION'
tag-template: 'v$NEXT_PATCH_VERSION'
categories:
  - title: 'Neue Features'
    labels:
      - 'feature'
template: |
  ## Neuerungen in dieser Version

  $CHANGES

  ### Detaillierte Änderungen
  $CATEGORIES

  ## Vollständiges Changelog
  $FULL_HISTORY

In dieser Konfiguration:

name-template und tag-template definieren, wie die Version und der Tag des Releases benannt werden, basierend auf der automatischen Versionserhöhung.
categories teilt die Pull Requests basierend auf ihren Labels in Gruppen ein, hier speziell für "feature".
template strukturiert die Release Notes und verwendet Platzhalter wie $CHANGES und $CATEGORIES für eine strukturierte Ausgabe.

Beispielszenario

Angenommen, PR1 und PR2 werden wie folgt gelabelt:

PR1 ist mit dem Label feature versehen.
PR2 ist ebenfalls mit dem Label feature versehen.

Wie die Release Notes aussehen könnten:

## Neuerungen in dieser Version

- Feature A - Das Feature A ist sehr gut (#PR-Nummer)
- Feature B - Das Feature B eröffnet neue Möglichkeiten (#PR-Nummer)

### Detaillierte Änderungen

#### Neue Features
- **Feature A**: Das Feature A ist sehr gut - Dieser Pull Request bringt ein neues Feature, das sehr gut ist. ([#PR-Nummer](PR-Link))
- **Feature B**: Das Feature B eröffnet neue Möglichkeiten - Dieser Pull Request führt Feature B ein, das neue Möglichkeiten eröffnet. ([#PR-Nummer](PR-Link))

## Vollständiges Changelog
- Alle Änderungen ansehen auf [GitHub](Link-zum-Repo-Tag)

Erklärung der Platzhalter:

$CHANGES wird durch eine Liste aller Änderungen ersetzt, die in den Pull Requests vorgenommen wurden, jeweils mit Titel und einer kurzen Beschreibung, wenn angegeben.
$CATEGORIES listet alle Änderungen, die unter die spezifizierten Kategorien fallen, hier "Neue Features".
$FULL_HISTORY bietet einen Link zum vollständigen Changelog auf GitHub.

Dieses Format hilft dabei, sowohl eine hohe Übersicht als auch detaillierte Informationen bereitzustellen, wobei die wichtigen Details aus jedem PR klar hervorgehoben werden. Je nach Bedarf können weitere Anpassungen vorgenommen werden, etwa durch zusätzliche Kategorisierungen oder veränderte Template-Strukturen, um die Relevanz und Klarheit der Release Notes weiter zu verbessern.

Ich finde das grossartig, genau das brauche ich. Die Fettschrift Feature A und Feature B macht er also selbstständig und auch die unsortierten Listen. Denn genau damit habe ich das Zuordnungsproblem gelöst (welcher Detailtext zu welchem Feature).

Es freut mich zu hören, dass das Beispiel genau das ist, was du benötigst! Tatsächlich, der Release Drafter bietet eine flexible Möglichkeit, die Informationen aus Pull Requests strukturiert und übersichtlich darzustellen. Jedoch gibt es ein kleines Missverständnis bezüglich der Formatierung wie Fettschrift und die automatische Erstellung unsortierter Listen.

Hier ist, was du wissen solltest:

Automatische Fettschrift: Release Drafter selbst fügt keine Fettschrift oder andere spezifische Formatierungen hinzu, es sei denn, du definierst dies in deinem Template in der release-drafter-config.yml-Datei. Um Fettschrift zu erzielen, müsstest du die Markdown-Syntax manuell in deinem Template verwenden. Zum Beispiel:
```
template: |
 ## Neuerungen in dieser Version

 $CHANGES

 ### Detaillierte Änderungen

 $CATEGORIES

 ## Vollständiges Changelog
 $FULL_HISTORY
```
Und in den $CATEGORIES könntest du definieren:
```
categories:
 - title: 'Neue Features'
   labels:
     - 'feature'
   format: '**{{title}}**: {{body}} ([#{{number}}]({{html_url}}))'
```
Hierbei wird {{title}} fett gedruckt dargestellt.
Listenformatierung: Der Platzhalter $CHANGES und $CATEGORIES werden in einer Liste dargestellt, basierend auf den Pull Requests, die zu den jeweiligen Labels passen. Die Listenelemente werden automatisch aus den Titeln und Körpern der Pull Requests generiert. Die spezifische Struktur und das Format dieser Liste kannst du durch die Anpassung deines Templates steuern.
Zuordnungsproblem: Indem du Labels und eventuell spezifische Templates für verschiedene Kategorien verwendest, kannst du sicherstellen, dass jedes Feature und jeder Bugfix klar identifiziert und entsprechend gruppiert wird. Dies hilft bei der klaren Zuordnung von Details zu den jeweiligen Features oder Änderungen.

Beispiel für erweiterte Template-Anpassung:

Wenn du sicherstellen möchtest, dass jedes Feature besonders hervorgehoben wird, könnte dein Template so aussehen:

categories:
  - title: 'Neue Features'
    labels:
      - 'feature'
    format: '**{{title}}**: {{body}} - [#{{number}}]({{html_url}})'

Dieses Format nutzt Markdown, um den Titel des Pull Requests fett zu drucken und den Link zum Pull Request anzufügen, was die Navigation und Verfolgung erleichtert.

Indem du die Vorlagen und Kategorisierungen nach deinen Bedürfnissen anpasst, kannst du eine sehr effektive und informative Zusammenstellung der Release Notes erreichen, die den Überblick über neue Features und Änderungen vereinfacht.

Welche Anpassungen müsste ich also beim bisherigen Template machen?

# Konfigurationsdatei für das Release-Drafter-Tool.
# release-drafter-config.yml

# Definiert die Vorlage für den Namen des Releases.
name-template: 'v$RESOLVED_VERSION' # Automatisch erhöhte Versionsnummer

# Definiert die Vorlage für den Namen des Release-Tags.
tag-template: 'v$RESOLVED_VERSION' # Automatisch erhöhte Versionsnummer

# Definiert die Kategorien, die im Changelog angezeigt werden. Jede Kategorie kann
# durch ein oder mehrere Labels identifiziert werden. Pull Requests, die diese Labels verwenden,
# werden automatisch unter der entsprechenden Kategorie im Changelog aufgeführt.
categories:
  - title: 'Features'
    labels:
      - 'enhancement'
  - title: 'Bug Fixes'
    labels:
      - 'bug'
  - title: 'Dokumentation'
    labels:
      - 'documentation'

# Definiert das allgemeine Layout des Changelogs.
# $CHANGES wird durch die Liste der Änderungen ersetzt, die gemäß `change-template` formatiert sind.
template: |
  ## Änderungen
  $CHANGES

# Definiert die Kategorien, die im Changelog angezeigt werden. Jede Kategorie kann
# durch ein oder mehrere Labels identifiziert werden. Pull Requests, die diese Labels verwenden,
# werden automatisch unter der entsprechenden Kategorie im Changelog aufgeführt.
# Standardmäßig wird die Patch-Version erhöht. Für Minor-Updates wird ein entsprechendes Label benötigt.
# Major-Updates werden manuell verwaltet und sind nicht automatisiert.
version-resolver:
  major:
    labels:
      - 'breaking'
  minor:
    labels:
      - 'enhancement'
  patch:
    labels:
      - 'bug'
      - 'documentation'
  default: minor

Um das bestehende Template in deiner release-drafter-config.yml Datei zu verbessern und es mehr deinen Bedürfnissen anzupassen, wie zum Beispiel das Hervorheben von Feature-Titeln und eine genauere Formatierung der Änderungen, könntest du einige spezifische Anpassungen vornehmen. Hier sind einige Vorschläge:

1. Einführung eines spezifischeren Templates für die Kategorien

Um jedes Feature oder jede Änderung deutlich hervorzuheben, könntest du das Format für die Einträge innerhalb jeder Kategorie anpassen. Dies wird besonders nützlich sein, um direkt im Changelog sichtbar zu machen, welche Pull Requests welche Features oder Fixes beinhalten.

Beispiel für ein angepasstes Format:

categories:
  - title: 'Features'
    labels:
      - 'enhancement'
    format: '**{{title}}**: {{body}} - ([#{{number}}]({{html_url}}))'
  - title: 'Bug Fixes'
    labels:
      - 'bug'
    format: '**{{title}}**: {{body}} - ([#{{number}}]({{html_url}}))'
  - title: 'Dokumentation'
    labels:
      - 'documentation'
    format: '**{{title}}**: {{body}} - ([#{{number}}]({{html_url}}))'

In diesem Format wird der Titel jedes Pull Requests fett gedruckt, gefolgt von einer kurzen Beschreibung (Body des PRs) und einem Link zum PR für schnellen Zugriff. Das erleichtert es, spezifische Änderungen schnell zu identifizieren und nachzuvollziehen.

2. Erweiterte Nutzung des `$CATEGORIES` Platzhalters

Wenn du die $CATEGORIES Variable in deinem Template nutzt, kannst du eine differenzierte Anzeige der Kategorien erreichen, was die Übersichtlichkeit erhöht.

Beispiel für ein erweitertes Haupttemplate:

template: |
  ## Änderungen in Version $NEXT_PATCH_VERSION
  Hier sind die Hauptänderungen in dieser Version:
  $CATEGORIES

  ## Vollständiges Changelog
  Für eine detailliertere Übersicht besuchen Sie bitte: [Changelog]($FULL_HISTORY)

3. Hinzufügen von Versionsinformationen

Die Konfiguration der version-resolver sieht gut aus und sollte für die automatische Versionierung deiner Releases auf Basis der Labels effektiv funktionieren. Du könntest zusätzlich den $RESOLVED_VERSION Platzhalter nutzen, um die genaue Versionsnummer an verschiedenen Stellen in deinen Release Notes zu erwähnen.

Schlussfolgerung

Diese Anpassungen sorgen dafür, dass dein Changelog klar strukturiert ist und die Informationen gut sichtbar sind. Es hebt wichtige Änderungen hervor und bietet direkte Links zu den detaillierteren Pull Requests, was die Nachvollziehbarkeit verbessert. Außerdem stellt das verbesserte Template sicher, dass jede Kategorie richtig formatiert und leicht zugänglich ist, was sowohl für Entwickler als auch für Stakeholder von Vorteil ist.

Das werde ich ausprobieren. Ich wusste nicht, dass der Release Drafter so detailliert formatieren kann?

Kann er sonst noch etwas von dem ich wissen sollte?

Der Release Drafter ist ein ungemein nützliches Tool, wenn es darum geht, den Prozess der Release-Notiz-Erstellung zu automatisieren und zu standardisieren. Hier sind einige zusätzliche Funktionen und Möglichkeiten, die der Release Drafter bietet, und die vielleicht interessant für dich sein könnten:

1. Dynamische Versionierung

Der Release Drafter kann die nächste Versionsnummer basierend auf den vorgenommenen Änderungen automatisch erhöhen. Durch die Verwendung von Labels wie breaking, enhancement, oder bug kann der Release Drafter entscheiden, ob ein Major-, Minor- oder Patch-Update erforderlich ist. Diese dynamische Versionierung hilft dabei, den semantischen Versionierungsstandards zu folgen, ohne dass manuell eingegriffen werden muss.

2. Automatische Changelog-Erstellung

Wie bereits gesehen, kann der Release Drafter das Changelog basierend auf den zusammengefassten Pull Requests automatisch erstellen. Das Changelog wird strukturiert nach den definierten Kategorien, was hilft, eine klare Übersicht über die Arten von Änderungen zu erhalten, die mit jedem Release eingeführt werden.

3. Anpassbare Templates

Der Release Drafter ermöglicht eine hohe Anpassbarkeit der Templates, die verwendet werden, um die Release Notes zu formatieren. Du kannst Markdown verwenden, um die Ausgabe zu gestalten, Links hinzufügen, Listen erstellen, und sogar bedingte Logiken anwenden, abhängig von den spezifischen Bedürfnissen deines Projekts.

4. Verwendung von Platzhaltern

Release Drafter unterstützt verschiedene Platzhalter wie $CHANGES, $CATEGORIES, $CONTRIBUTORS, $RESOLVED_VERSION, und $FULL_HISTORY, die helfen, die Release Notes dynamisch mit relevanten Informationen zu füllen. Diese Platzhalter erleichtern die Automatisierung und stellen sicher, dass keine wichtigen Details übersehen werden.

5. Integration mit GitHub Actions

Release Drafter lässt sich nahtlos in GitHub Actions integrieren. Dies bedeutet, dass er als Teil des CI/CD-Pipelines ausgelöst werden kann, um die Release Notes zu generieren, sobald ein neues Release vorbereitet wird.

6. Unterstützung für Mehrfachkonfigurationen

Du kannst mehrere Konfigurationsdateien in einem einzigen Repository haben, wenn dein Projekt verschiedene Release-Ströme oder Produktlinien hat, die unterschiedlich gehandhabt werden müssen. Dies ist besonders nützlich in größeren Projekten, die modular aufgebaut sind.

7. Community und Erweiterungen

Da der Release Drafter ein Open-Source-Projekt ist und eine breite Community hat, gibt es ständige Verbesserungen und Erweiterungen. Es gibt auch eine Vielzahl von Forks und Plugins, die zusätzliche Funktionalitäten bieten, wie das Hinzufügen von Labels direkt aus den Release Notes heraus oder das Erstellen von detaillierteren Berichten über Änderungen.

Diese Funktionen machen den Release Drafter zu einem extrem mächtigen Tool für jeden, der automatisierte, konsistente und informative Release Notes in seinen Softwareentwicklungsprozess integrieren möchte.

kurmann / GitHub.Workflows