Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen.

Version 1.0.0
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
### Changed
- Update and improvement of Polish translation from [@m-aciek](https://github.com/m-aciek).

## [1.0.0] - 2017-06-20
### Added
- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@karalamalar](https://github.com/karalamalar).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portugese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs"
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03
### Added
- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can
benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.

### Changed
- Clarified the section on "Is there a standard change log format?".

### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.

## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.

## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## 0.0.1 - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2

Was ist ein Changelog?

Ein Changelog ist eine Datei, die eine handgepflegte, chronologisch sortierte Liste aller erheblichen Änderungen enthält, die zwischen einzelnen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden.

Was ist der Zweck eines Changelogs?

Ein Changelog soll es Benutzern und Entwicklern einfacher machen, gerade die beachtenswerten Änderungen, die zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

Wer braucht schon ein Changelog?

Menschen brauchen es. Seien es Konsumenten oder Entwickler, die Endnutzer der Software sind Menschen, die es interessiert, was in der Software passiert. Wenn sich die Software ändert, dann wollen diese Menschen wissen, wie und warum sie sich ändert.

Wie erstelle ich einen guten Changelog?

Grundlegende Prinzipien

  • Changelogs werden für Menschen geschrieben, nicht für Maschinen.
  • Für jede einzelne Version sollte es einen Eintrag geben.
  • Änderungen der selben Art sollten in Bereiche gruppiert werden.
  • Versionen und Bereiche sollten verlinkt werden können.
  • Die neuste Version kommt als erstes.
  • Das Release-Datum jeder Version muss angegeben sein.
  • Gib an, ob du dich an die Semantische Versionierung hältst.

Arten von Änderungen

  • Added für neue Features.
  • Changed für Änderungen an der bestehenden Funktionalität.
  • Deprecated für Features, die in zukünftigen Versionen entfernt werden.
  • Removed für Deprecated-Features, die in dieser Version entfernt wurden.
  • Fixed für alle Bug-Fixes.
  • Security um Benutzer im Fall von geschlossenen Sicherheitslücken zu einer Aktualisierung aufzufordern.

Wie kann ich den Aufwand der Changelog-Pflege so klein wie möglich halten?

Habe immer einen Unreleased-Abschnitt über der neusten Version, um zukünftige Änderungen im Auge zu behalten.

Dies hat zwei Vorteile:

  • Menschen können sehen, welche Änderungen sie mit dem nächsten Release zu erwarten haben.
  • Wenn der Zeitpunkt für den Release gekommen ist, kannst du den Inhalt des Unreleased-Abschnitts in den neuen Release-Abschnitt verschieben.

Kann man beim Changelog etwas falsch machen?

Ja. Hier sind einige Dinge, die eher unbrauchbar sind.

Einen Diff von Commit-Logs ausgeben

Commit-Logs in einem Changelog sind eine schlechte Idee: Sie beinhalten lauter überflüssige Dinge, wie Merge-Commit, Commits mit schlechten Bezeichnungen, Änderungen an der Dokumentation, etc.

Der Sinn eines Commits ist die Entwicklung des Source Code zu dokumentieren. Manche Projekte haben saubere Commits, andere nicht.

Der Sinn eines Changelog-Eintrags ist die Dokumentation der merkbaren Unterschiede, die meist über mehrere Commits hinweg entstanden sind, dem Endnutzer klar und deutlich zu kommunizieren.

Features ohne Deprecation-Warnung entfernen

Wenn der Endnutzer auf eine neue Version upgradet, sollte ihm unmissverständlich klar gemacht werden, wenn etwas kaputt gehen wird. Es sollte immer möglich sein, zu einer Version zu upgraden, die die zu entfernenden Features auflistet, um so in seinem Source Code auf diese Features zu verzichten. Anschließend sollte man auf eine Version upgraden können, in der die Features entfernt wurden.

Auch wenn du sonst nichts geändert hast, liste trotzdem alle veralteten und entfernten Features, sowie jede funktionsgefährdende Änderung in deinem Changelog auf.

Verwirrende Datumsformate

In den USA setzen die Menschen den Monat an den Anfang eines Datums (06-02-2012 für den 2. Juni 2012), wohingegen viele Menschen im Rest der Welt ein roboterhaft aussehendes 2 June 2012 schreiben, aber es völlig unterschiedlich aussprechen. 2012-06-02 folgt der Logik vom größten zum kleinsten Wert, kann nicht mit anderen Formaten verwechselt werden und ist ein ISO Standard. Deshalb ist es das empfohlene Datumsformat in Changelogs.

Häufig gestellte Fragen

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Es gibt zwar den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden". Beide sind aber unzureichend.

Dieses Projekt versucht eine bessere Changelog Konvention zu sein. Dazu beobachten wir bewährte Praktiken aus der Open Source Community und tragen sie zusammen.

Gesunde Kritik, Diskussionen und Verbesserungsvorschläge sind herzlich willkommen.

Wie sollte die Changelog-Datei benannt sein?

Nenne sie CHANGELOG.md. Manche Projekte verwenden auch HISTORY, NEWS oder RELEASES.

Man könnte zwar meinen, dass der Name der Changelog-Datei keine große Bedeutung hat, aber warum sollte man es den Endnutzern nicht einfach machen, die Änderungen des Projekts zu finden, indem man einen einheitlichen Namen verwendet?

Was ist mit GitHub Releases?

Prinzipiell sind GitHub Releases eine gute Sache. Sie können dazu benutzt werden, um einfache Git Tags (zum Beispiel einen Tag namens v1.0.0) mit vielen Hinweisen zum Release auszustatten, indem man sie manuell bearbeitet, oder die Änderungen in eine Git Tag Nachricht schreibt, wo sie durch GitHub automatisch in die Release-Notizen gesetzt werden.

Leider lassen sich GitHub Releases aber nicht so einfach exportieren und sind nur über GitHub selber zu lesen. Man kann sie auch so gestalten, dass sie dem Keep a Changelog Format sehr ähnlich sehen, aber dazu betreibt man in der Regel einen größeren Aufwand.

Die derzeitige Version der GitHub Releases sind außerdem nicht leicht durch die Endnutzer zu finden, ganz im Gegenteil zu den typischerweise großgeschriebenen Dateien (README, CONTRIBUTING, etc.). Ein weiterer kleiner Nachteil ist, dass das Web Interface zurzeit keinen Link anbietet, um die Commits zwischen einzelnen Releases miteinander zu vergleichen.

Können Changelogs automatisiert ausgelesen werden?

Es ist schwierig, weil Menschen meist unterschiedliche Formate und Dateinamen verwenden.

Vandamme ist ein Ruby gem erstellt vom Gemnasium Team, das viele (aber nicht alle) Changelogs von Open-Source-Projekten einlesen kann.

Wie sieht es mit zurückgezogenen Releases aus?

Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen diese im Changelog gar nicht vor, aber das sollten sie. So solltest Du diese Versionen darstellen:

## 0.0.5 - 2014-12-13 [YANKED]

Der [YANKED] ist nicht ohne Grund großgeschrieben. Es ist wichtig, dass sie von Menschen bemerkt werden. Weil er von eckigen Klammern umgeben ist, kann man sie außerdem einfacher automatisiert einlesen.

Sollte ich ein Changelog je umschreiben?

Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne regelmässig Pull Requests, um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen.

Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.

Wie kann ich mithelfen?

Dieses Dokument ist nicht die Wahrheit. Es ist meine wohl überlegte Meinung, zusammen mit von mir zusammengetragenen Informationen und Beispielen.

So möchte ich erreichen, dass die Community einen Konsens findet. Ich glaube, dass die Disskussion genauso wichtig ist wie das Endergebnis.

Also bitte bring dich ein.

Gespräche

Ich habe im The Changelog podcast darüber gesprochen, warum sich Entwickler und Mitwirkende eines Projekts um ein Changelog kümmern sollten, sowie meine Motivationen hinter diesem Projekt erklärt.