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