Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen

Version 0.3.0

Was ist ein Changelog?

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

# 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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [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 [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- 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).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### 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.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[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
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

Was ist der Zweck eines Changelogs?

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

Warum sollte mich das kümmern?

Weil Software-Werkzeuge für Menschen gemacht sind. Wenn es Dich nicht kümmert, warum trägst Du dann zu Open Source bei? Wenn Du tief in Dich gehst, findest Du bestimmt einen kleinen Teil, dem das wichtig ist.

Ich habe mit Adam Stacoviak and Jerod Santo im The Changelog-Podcast (passt, oder?) darüber gesprochen (Englisch), weshalb sich Entwickler darum kümmern sollten und über die Beweggründe hinter diesem Projekt. Falls Du die Zeit hast (1:06), es lohnt sich, reinzuhören.

Was macht ein gutes Changelog aus?

Schön, dass Du fragst.

Ein gutes Changelog hält sich an die folgenden Prinzipien:

Wie kann ich den Aufwand so klein wie möglich halten?

Hab immer einen "Unreleased"-Abschnitt zuoberst, um Änderungen im Auge zu behalten.

Dies verfolgt zwei Ziele:

Was bringt Einhörner zum weinen?

Also… Schauen wir uns das an.

Das war noch nicht alles. Hilf mir, diese Einhorn-Tränen zu sammeln und eröffne ein Issue oder einen Pull-Request.

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Beruhige Dich. Ich weiss, dass Du wie wild nach dem Link für den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden" suchst. Der GNU Styleguide ist ein guter Anfang, aber er ist leider sehr naiv. Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt.

Dieses Projekt enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten Software-Projekten entnehmen. Schau Dich um und denk daran, dass Diskussionen und Verbesserungsvorschläge sehr willkommen sind!

Wie soll ich meine Changelog-Datei nennen?

Nun, falls Du es noch nicht am Beispiel oben gesehen hast, CHANGELOG.md ist bisher die beste Konvention.

Einige Projekte nutzen auch HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Es ist ein Chaos. Alle diese Namen machen es nur schwerer, die Datei zu finden.

Wieso sollte man nicht einfach ein git log Diff verwenden?

Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien zu comitten und nie einen Teil eines Refactorings übersehen. Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren, welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs ist es, die nennenswerten Veränderungen zwischen diesen Zuständen zu dokumentieren.

Der Unterschied zwischen dem Changelog und dem Commit-Log ist wie der Unterschied zwischen guten Kommentaren und dem Code selbst: Das eine beschreibt das wieso, das andere das wie.

Kann man Changelogs automatisiert parsen?

Es ist nicht einfach, weil äusserst unterschiedliche Formate und Dateinamen verwendet werden.

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

Wieso schreibst Du mal "CHANGELOG" und mal "Changelog"?

"CHANGELOG" ist der Name der Datei selbst. Es ist ein bisschen laut, aber es ist eine historische Konvention, welche von vielen Open-Source-Projekten angewendet wird. Andere Beispiele von ähnlichen Dateien sind README, LICENSE und CONTRIBUTING.

Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat, dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln möchte, ähnlich wie Open-Source-Projekt-Badges.

Wenn ich über ein "Changelog" spreche, dann meine ich die Funktion der Datei: das Festhalten von Änderungen.

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. Das sollten sie aber. So solltest Du diese darstellen:

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

Das [YANKED]-Tag ist aus einem guten Grund laut. Es ist wichtig, dass es wahrgenommen wird. Dass es von Klammern umfasst ist, vereinfacht auch das automatisierte Parsen.

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. Obwohl ich im GitHub-Repository ein CHANGELOG führe, habe ich keine echten Releases oder klare zu befolgenden Regeln geschrieben (wie dies zum Beispiel SemVer.org tut).

Das ist so, weil ich möchte, dass die Community sich einig wird. Ich glaube, dass die Diskussion genau so wichtig wie das Endresultat ist.

Deshalb pack bitte mit an.