From b695d5e30a87a8d574ad21393a037710396f27d3 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Fri, 27 Mar 2020 20:06:12 +0100
Subject: [PATCH] Add guidance on writing and maintaining changelog entries

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 ChangeLog.d/00README.md       | 55 ++++++++++++++++++++++++++++++++---
 scripts/assemble_changelog.py |  2 ++
 2 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/ChangeLog.d/00README.md b/ChangeLog.d/00README.md
index 774460d6b..b559e2336 100644
--- a/ChangeLog.d/00README.md
+++ b/ChangeLog.d/00README.md
@@ -1,6 +1,10 @@
+# Pending changelog entry directory
+
 This directory contains changelog entries that have not yet been merged
 to the changelog file ([`../ChangeLog`](../ChangeLog)).
 
+## Changelog entry file format
+
 A changelog entry file must have the extension `*.txt` and must have the
 following format:
 
@@ -10,11 +14,54 @@ Security
    * Another change description.
 
 Features
-   * Yet another change description.
+   * Yet another change description. This is a long change description that
+     spans multiple lines.
    * Yet again another change description.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See `STANDARD_CATEGORIES` in
-[`../scripts/assemble_changelog.py`](../scripts/assemble_changelog.py)
-for recognized section titles.
+The permitted changelog entry categories are as follows:
+<!-- Keep this synchronized with STANDARD_CATEGORIES in assemble_changelog.py! -->
+
+    API changes
+    Default behavior changes
+    Requirement changes
+    New deprecations
+    Removals
+    Features
+    Security
+    Bugfix
+    Changes
+
+Use “Changes” for anything that doesn't fit in the other categories, such as
+performance, documentation and test improvements.
+
+## How to write a changelog entry
+
+Each entry starts with three spaces, an asterisk and a space. Continuation
+lines start with 5 spaces. Lines wrap at 79 characters.
+
+Write full English sentences with proper capitalization and punctuation. Use
+the present tense. Use the imperative where applicable. For example: “Fix a
+bug in mbedtls_xxx() ….”
+
+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.
+
+**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
+consequences of the bug, not how the bug was fixed. For a new feature, explain
+why one might be interested in the feature. For an API change or a deprecation,
+explain how to update existing applications.
+
+See [existing entries](../ChangeLog) for examples.
+
+## How `ChangeLog` is updated
+
+Run [`../scripts/assemble_changelog.py`](../scripts/assemble_changelog.py)
+from a Git working copy
+to move the entries from files in `ChangeLog.d` to the main `ChangeLog` file.
diff --git a/scripts/assemble_changelog.py b/scripts/assemble_changelog.py
index 57440bbb3..d11e2e8ba 100755
--- a/scripts/assemble_changelog.py
+++ b/scripts/assemble_changelog.py
@@ -62,6 +62,8 @@ class LostContent(Exception):
         message = ('Lost content from {}: "{}"'.format(filename, line))
         super().__init__(message)
 
+# The category names we use in the changelog.
+# If you edit this, update ChangeLog.d/README.md.
 STANDARD_CATEGORIES = (
     b'API changes',
     b'Default behavior changes',