Our releases are accompanied by changelogs based on the Keep a Changelog format. We are using the towncrier utility to generate them at the time a new version is released. There are currently four such changelogs for different components of the repository:

Adding changelog entry

towncrier aims to create changelogs that are convenient to read, at the expense of being somewhat inconvenient to create. Furthermore every changelog entry has to be linked to a GitHub issue or pull request number. If you don't want to create an issue just to satisfy this rule you can use self-reference to your change's pull request number by first creating the PR and then adding the entry.

There are a few types of changelog entries, as described by the Keep a Changelog format:

  • added
  • changed
  • deprecated
  • removed
  • fixed
  • security
  • incompatible (for backwards incompatible changes)

Entries are added by creating files in the .changelog.d directory where the file name is <number>.<type> and contains single line describing the change. As an example, an entry describing bug fix for issue 1234 in Trezor T firmware is added by creating file core/.changelog.d/1234.fixed. The file can be formatted with markdown. If more entries are desired for single issue number and type you can add numeral suffix, e.g. 1234.fixed.1, 1234.fixed.2, etc.

You can also add this entry using your $VISUAL editor by running towncrier create --edit 1234.fixed in the core directory.

Generating changelog at the time of release

When it's time to release new version of a repository component the formatted changelog needs to be generated using the tools/ script. It accepts repo subdirectory and the version number as arguments and you can specify the release date if it's different from today's date:

tools/ --date "20th April 2021" legacy/firmware 1.10.0

Cherry-picking changes to release branch

Branches named release/YY.MM already have their corresponding section generated. When cherry-picking bug fix to such branch you need to bypass towncrier and edit directly.