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 25Until Mbed TLS 2.24.0, we required changelog entries in more cases. 26Looking at older changelog entries is good practice for how to write a 27changelog entry, but not for deciding whether to write one. 28 29## Changelog entry file format 30 31A changelog entry file must have the extension `*.txt` and must have the 32following format: 33 34~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 35Security 36 * Change description. 37 * Another change description. 38 39Features 40 * Yet another change description. This is a long change description that 41 spans multiple lines. 42 * Yet again another change description. 43 44~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 45 46The permitted changelog entry categories are as follows: 47<!-- Keep this synchronized with STANDARD_CATEGORIES in assemble_changelog.py! --> 48 49 API changes 50 Default behavior changes 51 Requirement changes 52 New deprecations 53 Removals 54 Features 55 Security 56 Bugfix 57 Changes 58 59Use “Changes” for anything that doesn't fit in the other categories. 60 61## How to write a changelog entry 62 63Each entry starts with three spaces, an asterisk and a space. Continuation 64lines start with 5 spaces. Lines wrap at 79 characters. 65 66Write full English sentences with proper capitalization and punctuation. Use 67the present tense. Use the imperative where applicable. For example: “Fix a 68bug in mbedtls_xxx() ….” 69 70Include GitHub issue numbers where relevant. Use the format “#1234” for an 71Mbed TLS issue. Add other external references such as CVE numbers where 72applicable. 73 74Credit bug reporters where applicable. 75 76**Explain why, not how**. Remember that the audience is the users of the 77library, not its developers. In particular, for a bug fix, explain the 78consequences of the bug, not how the bug was fixed. For a new feature, explain 79why one might be interested in the feature. For an API change or a deprecation, 80explain how to update existing applications. 81 82See [existing entries](../ChangeLog) for examples. 83 84## How `ChangeLog` is updated 85 86Run [`../scripts/assemble_changelog.py`](../scripts/assemble_changelog.py) 87from a Git working copy 88to move the entries from files in `ChangeLog.d` to the main `ChangeLog` file. 89