1# Maintained branches 2 3At any point in time, we have a number of maintained branches, currently consisting of: 4 5- The [`master`](https://github.com/Mbed-TLS/mbedtls/tree/master) branch: 6 this always contains the latest release, including all publicly available 7 security fixes. 8- The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch: 9 this is where the current major version of Mbed TLS (version 3.x) is being 10 prepared. It has API changes that make it incompatible with Mbed TLS 2.x, 11 as well as all the new features and bug fixes and security fixes. 12- One or more long-time support (LTS) branches: these only get bug fixes and 13 security fixes. Currently, the only supported LTS branch is: 14 [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28). 15 16We retain a number of historical branches, whose names are prefixed by `archive/`, 17such as [`archive/mbedtls-2.7`](https://github.com/Mbed-TLS/mbedtls/tree/archive/mbedtls-2.7). 18These branches will not receive any changes or updates. 19 20We use [Semantic Versioning](https://semver.org/). In particular, we maintain 21API compatibility in the `master` branch across minor version changes (e.g. 22the API of 3.(x+1) is backward compatible with 3.x). We only break API 23compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain 24ABI compatibility within LTS branches; see the next section for details. 25 26## Backwards Compatibility for application code 27 28We maintain API compatibility in released versions of Mbed TLS. If you have 29code that's working and secure with Mbed TLS x.y.z and does not rely on 30undocumented features, then you should be able to re-compile it without 31modification with any later release x.y'.z' with the same major version 32number, and your code will still build, be secure, and work. 33 34Note that this guarantee only applies if you either use the default 35compile-time configuration (`mbedtls/mbedtls_config.h`) or the same modified 36compile-time configuration. Changing compile-time configuration options can 37result in an incompatible API or ABI, although features will generally not 38affect unrelated features (for example, enabling or disabling a 39cryptographic algorithm does not break code that does not use that 40algorithm). 41 42Note that new releases of Mbed TLS may extend the API. Here are some 43examples of changes that are common in minor releases of Mbed TLS, and are 44not considered API compatibility breaks: 45 46* Adding or reordering fields in a structure or union. 47* Removing a field from a structure, unless the field is documented as public. 48* Adding items to an enum. 49* Returning an error code that was not previously documented for a function 50 when a new error condition arises. 51* Changing which error code is returned in a case where multiple error 52 conditions apply. 53* Changing the behavior of a function from failing to succeeding, when the 54 change is a reasonable extension of the current behavior, i.e. the 55 addition of a new feature. 56 57There are rare exceptions where we break API compatibility: code that was 58relying on something that became insecure in the meantime (for example, 59crypto that was found to be weak) may need to be changed. In case security 60comes in conflict with backwards compatibility, we will put security first, 61but always attempt to provide a compatibility option. 62 63## Backward compatibility for the key store 64 65We maintain backward compatibility with previous versions of the 66PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the 67storage backend (PSA ITS implementation) is configured in a compatible way. 68We intend to maintain this backward compatibility throughout a major version 69of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read 70keys written under any Mbed TLS 3.x with x <= y). 71 72Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x 73LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y) 74may require the use of an upgrade tool. 75 76Note that this guarantee does not currently fully extend to drivers, which 77are an experimental feature. We intend to maintain compatibility with the 78basic use of drivers from Mbed TLS 2.28.0 onwards, even if driver APIs 79change. However, for more experimental parts of the driver interface, such 80as the use of driver state, we do not yet guarantee backward compatibility. 81 82## Long-time support branches 83 84For the LTS branches, additionally we try very hard to also maintain ABI 85compatibility (same definition as API except with re-linking instead of 86re-compiling) and to avoid any increase in code size or RAM usage, or in the 87minimum version of tools needed to build the code. The only exception, as 88before, is in case those goals would conflict with fixing a security issue, we 89will put security first but provide a compatibility option. (So far we never 90had to break ABI compatibility in an LTS branch, but we occasionally had to 91increase code size for a security fix.) 92 93For contributors, see the [Backwards Compatibility section of 94CONTRIBUTING](CONTRIBUTING.md#backwards-compatibility). 95 96## Current Branches 97 98The following branches are currently maintained: 99 100- [master](https://github.com/Mbed-TLS/mbedtls/tree/master) 101- [`development`](https://github.com/Mbed-TLS/mbedtls/) 102- [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28) 103 maintained until at least the end of 2024, see 104 <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.3>. 105 106Users are urged to always use the latest version of a maintained branch. 107
