From 1ffd967411cd1d874c4d76fc179f846572cf300c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 30 Sep 2020 01:16:59 +0200 Subject: [PATCH] Explain when to write a changelog entry Signed-off-by: Gilles Peskine --- ChangeLog.d/00README.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md index abe0537ef..67c47c5e0 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.7.17, 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