From 27ed799109be5c00b59fbae29be037d304b9b940 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 30 Sep 2020 01:11:39 +0200 Subject: [PATCH 1/5] Remove changelog entries without a user-visible impact Signed-off-by: Gilles Peskine --- ChangeLog.d/comment_typo_in_mbedtls_ssl_set_bio.txt | 2 -- ChangeLog.d/fix-typo.txt | 3 --- 2 files changed, 5 deletions(-) delete mode 100644 ChangeLog.d/comment_typo_in_mbedtls_ssl_set_bio.txt delete mode 100644 ChangeLog.d/fix-typo.txt diff --git a/ChangeLog.d/comment_typo_in_mbedtls_ssl_set_bio.txt b/ChangeLog.d/comment_typo_in_mbedtls_ssl_set_bio.txt deleted file mode 100644 index 2f94c1633c..0000000000 --- a/ChangeLog.d/comment_typo_in_mbedtls_ssl_set_bio.txt +++ /dev/null @@ -1,2 +0,0 @@ -Changes - * Fix comment typo in documentation of mbedtls_ssl_set_bio. diff --git a/ChangeLog.d/fix-typo.txt b/ChangeLog.d/fix-typo.txt deleted file mode 100644 index 8e961d2805..0000000000 --- a/ChangeLog.d/fix-typo.txt +++ /dev/null @@ -1,3 +0,0 @@ -Changes - * Fixes a typo in the example code located in - program/pkey/ecdh_curve25519.c From 3b4edc78df42527eb63d765f54f778545a1d5613 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 30 Sep 2020 01:13:05 +0200 Subject: [PATCH 2/5] We no longer credit contributors in the changelog From now on, external contributions are no longer acknowledged in the changelog file. They of course remain acknowledged in the Git history. Signed-off-by: Gilles Peskine --- ChangeLog.d/00README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md index b559e2336c..abe0537efe 100644 --- a/ChangeLog.d/00README.md +++ b/ChangeLog.d/00README.md @@ -49,8 +49,7 @@ Include GitHub issue numbers where relevant. Use the format “#1234” for an Mbed TLS issue. Add other external references such as CVE numbers where applicable. -Credit the author of the contribution if the contribution is not a member of -the Mbed TLS development team. Also credit bug reporters where applicable. +Credit bug reporters where applicable. **Explain why, not how**. Remember that the audience is the users of the library, not its developers. In particular, for a bug fix, explain the From ece00a0cd06f5a49ede2a338567d75af0e433906 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 30 Sep 2020 01:16:59 +0200 Subject: [PATCH 3/5] 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 abe0537efe..ba20db32cb 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 From 4bcfe9269fb52683f684ef5f15da0f1f53987c49 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 30 Sep 2020 09:55:27 +0200 Subject: [PATCH 4/5] When to write a changelog: minor improvements Mention sample programs. Signed-off-by: Gilles Peskine --- ChangeLog.d/00README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md index ba20db32cb..ec61c525b0 100644 --- a/ChangeLog.d/00README.md +++ b/ChangeLog.d/00README.md @@ -7,9 +7,10 @@ to the changelog file ([`../ChangeLog`](../ChangeLog)). 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. +* Bug fixes in the library or in sample programs: fixing a security hole, + fixing broken behavior, fixing the build in some configuration or on some + platform, etc. +* New features in the library, new sample programs, 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. @@ -18,8 +19,8 @@ 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. +* Changes to parts of the code base that users don't interact with directly, + such as test code and test data. 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 From e9a1e13d62698b00d1eb60be27da6d362243aada Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 1 Oct 2020 00:35:49 +0200 Subject: [PATCH 5/5] 2.24.0 is still covered by the old policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit “Prior to Mbed TLS 2.24” suggests that 2.24 itself didn't use the old policy anymore, but it did. Change to “Until”, and also give the exact version number “2.24.0”. Signed-off-by: Gilles Peskine --- ChangeLog.d/00README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md index ec61c525b0..d2ea73d1c2 100644 --- a/ChangeLog.d/00README.md +++ b/ChangeLog.d/00README.md @@ -22,7 +22,7 @@ We generally don't include changelog entries for: * Changes to parts of the code base that users don't interact with directly, such as test code and test data. -Prior to Mbed TLS 2.24, we required changelog entries in more cases. +Until Mbed TLS 2.24.0, 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.