Changelog
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 8 such changelogs for different components of the repository:
core/CHANGELOG.md
for Trezor T firmwarecore/embed/boardloader/CHANGELOG.md
for Trezor T boardloadercore/embed/bootloader/CHANGELOG.md
for Trezor T bootloadercore/embed/bootloader_ci/CHANGELOG.md
for Trezor T CI bootloaderlegacy/firmware/CHANGELOG.md
for Trezor 1 firmwarelegacy/bootloader/CHANGELOG.md
for Trezor 1 bootloaderlegacy/intermediate_fw/CHANGELOG.md
for Trezor 1 intermediate firmwarepython/CHANGELOG.md
for Python client library
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 should 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. If this is not suitable, the word
noissue
can be used in place of the issue number.
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.
Changes that only affect a subset of hardware models
If an entry is only relevant for certain model, put the internal name in square
brackets at the beginning of the entry. If there are multiple relevant models,
separate them by comas. Examples: [T2T1] Fix some bug.
, [T2T1,T2W1] Fix all bugs.
.
Not adding changelog entry
If you don't add an entry for changes in your branch, the changelog prebuild
CI job will remind you by failing. Sometimes adding an entry does not really make
sense, in that case you can include [no changelog]
anywhere in the commit
message to exclude that commit from the check.
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/generate-changelog.py
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/generate-changelog.py --date "20th April 2021" legacy/firmware 1.10.0
Cherry-picking changes to release branch
Branches named release/YY.MM
already have their corresponding CHANGELOG.md
section generated. When cherry-picking bug fix to such branch you need to
bypass towncrier and edit CHANGELOG.md
directly.