diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md index abe0537ef..ba20db32c 100644 --- a/ChangeLog.d/00README.md +++ b/ChangeLog.d/00README.md @@ -3,6 +3,28 @@ This directory contains changelog entries that have not yet been merged to the changelog file ([`../ChangeLog`](../ChangeLog)). +## What requires a changelog entry? + +Write a changelog entry if there is a user-visible change. This includes: + +* Bug fixes: fixing a security hole, fixing broken behavior, fixing + the build in some configuration or on some platform, ... +* New features in the library or new platform support. +* Changes in existing behavior. These should be rare. Changes in features + that are documented as experimental may or may not be announced, depending + on the extent of the change and how widely we expect the feature to be used. + +We generally don't include changelog entries for: + +* Documentation improvements. +* Performance improvements, unless they are particularly significant. +* Changes that don't impact library users directly, for example new tests or + changes to the test framework. + +Prior to Mbed TLS 2.24, we required changelog entries in more cases. +Looking at older changelog entries is good practice for how to write a +changelog entry, but not for deciding whether to write one. + ## Changelog entry file format A changelog entry file must have the extension `*.txt` and must have the @@ -33,8 +55,7 @@ The permitted changelog entry categories are as follows: Bugfix Changes -Use “Changes” for anything that doesn't fit in the other categories, such as -performance, documentation and test improvements. +Use “Changes” for anything that doesn't fit in the other categories. ## How to write a changelog entry