1# Pending changelog entry directory
2
3This directory contains changelog entries that have not yet been merged
4to the changelog file ([`../ChangeLog`](../ChangeLog)).
5
6## What requires a changelog entry?
7
8Write a changelog entry if there is a user-visible change. This includes:
9
10* Bug fixes in the library or in sample programs: fixing a security hole,
11  fixing broken behavior, fixing the build in some configuration or on some
12  platform, etc.
13* New features in the library, new sample programs, or new platform support.
14* Changes in existing behavior. These should be rare. Changes in features
15  that are documented as experimental may or may not be announced, depending
16  on the extent of the change and how widely we expect the feature to be used.
17
18We generally don't include changelog entries for:
19
20* Documentation improvements.
21* Performance improvements, unless they are particularly significant.
22* Changes to parts of the code base that users don't interact with directly,
23  such as test code and test data.
24* Fixes for compiler warnings. Releases typically contain a number of fixes
25  of this kind, so we will only mention them in the Changelog if they are
26  particularly significant.
27
28Until Mbed TLS 2.24.0, we required changelog entries in more cases.
29Looking at older changelog entries is good practice for how to write a
30changelog entry, but not for deciding whether to write one.
31
32## Changelog entry file format
33
34A changelog entry file must have the extension `*.txt` and must have the
35following format:
36
37~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38Security
39   * Change description.
40   * Another change description.
41
42Features
43   * Yet another change description. This is a long change description that
44     spans multiple lines.
45   * Yet again another change description.
46
47~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48
49The permitted changelog entry categories are as follows:
50<!-- Keep this synchronized with STANDARD_CATEGORIES in assemble_changelog.py! -->
51
52    API changes
53    Default behavior changes
54    Requirement changes
55    New deprecations
56    Removals
57    Features
58    Security
59    Bugfix
60    Changes
61
62Use “Changes” for anything that doesn't fit in the other categories.
63
64## How to write a changelog entry
65
66Each entry starts with three spaces, an asterisk and a space. Continuation
67lines start with 5 spaces. Lines wrap at 79 characters.
68
69Write full English sentences with proper capitalization and punctuation. Use
70the present tense. Use the imperative where applicable. For example: “Fix a
71bug in mbedtls_xxx() ….”
72
73Include GitHub issue numbers where relevant. Use the format “#1234” for an
74Mbed TLS issue. Add other external references such as CVE numbers where
75applicable.
76
77Credit bug reporters where applicable.
78
79**Explain why, not how**. Remember that the audience is the users of the
80library, not its developers. In particular, for a bug fix, explain the
81consequences of the bug, not how the bug was fixed. For a new feature, explain
82why one might be interested in the feature. For an API change or a deprecation,
83explain how to update existing applications.
84
85See [existing entries](../ChangeLog) for examples.
86
87## How `ChangeLog` is updated
88
89Run [`../scripts/assemble_changelog.py`](../scripts/assemble_changelog.py)
90from a Git working copy
91to move the entries from files in `ChangeLog.d` to the main `ChangeLog` file.
92