Explain when to write a changelog entry
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md
index abe0537..12de259 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.
+
+Until Mbed TLS 2.16.8, 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 @@
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