How to Keep a Changelog in Markdown

Keep a Changelog is a standardized way to format a news file in Markdown.

This guide shows you how to configure towncrier for keeping a Markdown-based news file of a project without using any Python-specific features. Everything used here can be used with any other language or platform.

This guide makes the following assumptions:

Put the following into your pyproject.toml or towncrier.toml:

[tool.towncrier]
directory = "changelog.d"
filename = "CHANGELOG.md"
start_string = "<!-- towncrier release notes start -->\n"
underlines = ["", "", ""]
title_format = "## [{version}](https://github.com/twisted/my-project/tree/{version}) - {project_date}"
issue_format = "[#{issue}](https://github.com/twisted/my-project/issues/{issue})"

[[tool.towncrier.type]]
directory = "security"
name = "Security"
showcontent = true

[[tool.towncrier.type]]
directory = "removed"
name = "Removed"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecated"
name = "Deprecated"
showcontent = true

[[tool.towncrier.type]]
directory = "added"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "changed"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "fixed"
name = "Fixed"
showcontent = true

Next create the news fragment directory:

$ mkdir changelog.d

Next, create the news file with an explanatory header:

$ cat >CHANGELOG.md <<EOF
# 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).

This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/twisted/my-project/tree/main/changelog.d/>.

<!-- towncrier release notes start -->


EOF

Note

The two empty lines at the end are on purpose.

That’s it! You can start adding news fragments:

towncrier create -c "Added a cool feature!" 1.added.md
towncrier create -c "Changed a behavior!" 2.changed.md
towncrier create -c "Deprecated a module!" 3.deprecated.md
towncrier create -c "Removed a square feature!" 4.removed.md
towncrier create -c "Fixed a bug!" 5.fixed.md
towncrier create -c "Fixed a security issue!" 6.security.md
towncrier create -c "Fixed a security issue!" 7.security.md
towncrier create -c "A fix without an issue number!" +something-unique.fixed.md

After running towncrier build --yes --version 1.0.0 (you can ignore the Git error messages) your CHANGELOG.md looks like this:

# 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).

This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/twisted/my-project/tree/main/changelog.d/>.

<!-- towncrier release notes start -->

## [1.0.0](https://github.com/twisted/my-project/tree/1.0.0) - 2022-09-28


### Security

- Fixed a security issue! ([#6](https://github.com/twisted/my-project/issues/6), [#7](https://github.com/twisted/my-project/issues/7))


### Removed

- Removed a square feature! ([#4](https://github.com/twisted/my-project/issues/4))


### Deprecated

- Deprecated a module! ([#3](https://github.com/twisted/my-project/issues/3))


### Added

- Added a cool feature! ([#1](https://github.com/twisted/my-project/issues/1))


### Changed

- Changed a behavior! ([#2](https://github.com/twisted/my-project/issues/2))


### Fixed

- Fixed a bug! ([#5](https://github.com/twisted/my-project/issues/5))
- A fix without an issue number!

Pretty close, so this concludes this guide!

Note

  • The sections are rendered in the order the fragment types are defined.

  • Because towncrier doesn’t have a concept of a “previous version” (yet), the version links will point to the release tags and not to the compare link like in Keep a Changelog.

  • Keep a Changelog doesn’t have the concept of a uncategorized change, so the template doesn’t expect any.