change

Changed

• Updated dependencies

Changed

• Minor cleanup

What's Changed

• 0.7.3 by @f3ath in #22

Full Changelog: 0.7.2...0.7.3

Changed

• Bump depenencies

Changed

• Bumped dependencies

Added

• The `printChanges() function to print changes only and skip the header part

Added

• Keep freetext directly under release headings

Changed

• Min SDK version is 3.0.0

0.6.0 - 2023-02-14

Added

• You may pass an instance of markdown Document to the parseChangelog() to have fine-grained control over parsing, e.g. whether to encode HTML entities
• Support for [YANKED] releases

Changed

• Bumped markdown to 7.0.0
• Bumped marker to 0.5.0
• HTML entities (ampersands, quotes, etc) are NOT encoded by default

Added

• You may pass an instance of markdown Document to the parseChangelog() to have fine-grained control over parsing, e.g. whether to encode HTML entities
• Support for [YANKED] releases

Changed

• Bumped markdown to 7.0.0
• Bumped marker to 0.5.0
• HTML entities (ampersands, quotes, etc) are NOT encoded by default

Changed

• Updated dependencies: markdown to 6.0.0, marker to 0.4.0

Changed

• Bumped the versions of dependencies: markdown to 5.0.0, marker to 0.3.0, pub_semver to 2.1.1
• Bumped the SDK version to 2.16.2

Changed

• Updated dependencies
• Prevent adding an existing release

Changed

• Release date is now required for each version.
• Change types are not limited by the ones listed by semver.
• Parsing and printing moved to standalone functions.

Removed

• Dependency on maybe_just_nothing.
• Dependency on dart:io.
• Markdown-related parts of the API.
• The Changelog.release() method. This logic will be added directly to Cider.

Added

• RU translation from [@aishek].
• pt-BR translation from [@tallesl].
• es-ES translation from [@ZeliosAriex].

Changed

• Migrated to null safety
• The "Unreleased" section is hidden when empty

Changed

• Remove exclusionary mentions of "open source" since this project can benefit both "open" and "closed" source projects equally.

Changed

• Bump dependencies versions

Changed

• API has been reworked substantially

Removed

• CLI part. Use Cider

Added

• Answer "Should you ever rewrite a change log?".

Changed

• Improve argument against commit logs.
• Start following [SemVer] properly.

Added

• Support for changelogs with missing dates

Added

• Ability to parse changelog with missing change type

Changed

• Upgraded dependencies

Fixed

• Missing diff link was breaking the app

Added

• Collection.addText()
• MarkdownLine.parse()

Added

• A static fromLines() factory method

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.

Changed

• Updated dependencies

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.

Added

• New command 'print' to output a released version

Added

• README section on "yanked" releases.

Added

• Create CHANGELOG.md when missing

Added

• Markdown links to version tags on release headings.
• Unreleased section to gather unreleased changes and encourage note keeping prior to releases.

Added

• Support for multiple major versions in a single file

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.

Added

• Console app
• Changelog model

Changed

• BREAKING Total rework of the package

Added

• "Why should I care?" section mentioning The Changelog podcast.

Added

• Changelog.writeFile()

Added

• Explanation of the recommended reverse chronological release ordering.

Added

• Parsing from markdown
• Writing to markdown

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?

Not really. There's the GNU changelog style guide , or the two-paragraph-long GNU NEWS file "guideline". Both are inadequate or insufficient.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

Healthy criticism, discussion and suggestions for improvements are welcome.

What should the changelog file be named?

Call it CHANGELOG.md . Some projects use HISTORY , NEWS or RELEASES .

While it's easy to think that the name of your changelog file doesn't matter that much, why make it harder for your end users to consistently find notable changes?

What about GitHub Releases?

It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0 ) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.

GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.

The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files ( README , CONTRIBUTING , etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

Can changelogs be automatically parsed?

It’s difficult, because people follow wildly different formats and file names.

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project changelogs.

What about yanked releases?

Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions don't even appear in change logs. They should. This is how you should display them: