Skip to content

Latest commit

 

History

History
270 lines (191 loc) · 10.3 KB

CHANGELOG.md

File metadata and controls

270 lines (191 loc) · 10.3 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

  • Added Dutch translation

Fixed

  • Fixed foldouts in Dutch translation

1.1.0 - 2019-02-15

Added

  • Danish translation from @frederikspang.
  • Georgian translation from @tatocaster.
  • Changelog inconsistency section in Bad Practices

Changed

  • Fixed typos in Italian translation from @lorenzo-arena.
  • Fixed typos in Indonesian translation from @ekojs.

1.0.0 - 2017-06-20

Added

  • New visual identity by @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.
  • German translation from @mpbzh & @Art4.
  • Italian translation from @azkidenz.
  • Swedish translation from @magol.
  • Turkish translation from @emreerkan.
  • French translation from @zapashcanon.
  • Brazilian Portuguese translation from @Webysther.
  • Polish translation from @amielucha & @m-aciek.
  • Russian translation from @aishek.
  • Czech translation from @h4vry.
  • Slovak translation from @jkostolansky.
  • Korean translation from @pierceh89.
  • Croatian translation from @porx.
  • Persian translation from @Hameds.
  • Ukrainian translation from @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

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 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?"

What is a changelog? A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog? To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog? People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog? Guiding Principles Changelogs are for humans, not machines. There should be an entry for every single version. The same types of changes should be grouped. Versions and sections should be linkable. The latest version comes first. The release date of each version is displayed. Mention whether you follow Semantic Versioning. Types of changes Added for new features. Changed for changes in existing functionality. Deprecated for soon-to-be removed features. Removed for now removed features. Fixed for any bug fixes. Security in case of vulnerabilities. How can I reduce the effort required to maintain a changelog? Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

People can see what changes they might expect in upcoming releases At release time, you can move the Unreleased section changes into a new release version section. Can changelogs be bad? Yes. Here are a few ways they can be less than useful.

Commit log diffs Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Ignoring Deprecations When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.

Confusing Dates Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day. This format also doesn't overlap in ambiguous ways with other date formats, unlike some regional formats that switch the position of month and day numbers. These reasons, and the fact this date format is an ISO standard, are why it is the recommended date format for changelog entries.

There’s more. Help me collect these antipatterns by opening an issue or a pull request. Frequently Asked Questions Is there a standard changelog format? What should the changelog file be named? What about GitHub Releases? Can changelogs be automatically parsed? What about yanked releases? Should you ever rewrite a changelog? How can I contribute? Conversations I went on The Changelog podcast to talk about why maintainers and contributors should care about changelogs, and also about the motivations behind this project.

This project is MIT Licensed // Created & maintained by Olivier Lacan // Designed by Tyler Fortune