1# Maintained branches 2 3At any point in time, we have a number of maintained branches 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 new features land, 10 as well as bug fixes and security fixes. 11- One or more long-time support (LTS) branches: 12 these only get bug fixes and security fixes. 13 14We use [Semantic Versioning](https://semver.org/). In particular, we maintain 15API compatibility in the `master` branch between major version changes. We 16also maintain ABI compatibility within LTS branches; see the next section for 17details. 18 19Every major version will become an LTS branch when the next major version is 20released. We may occasionally create LTS branches from other releases at our 21discretion. 22When a new LTS branch is created, it usually remains supported for three years. 23 24## Backwards Compatibility for application code 25 26We maintain API compatibility in released versions of Mbed TLS. If you have 27code that's working and secure with Mbed TLS x.y.z and does not rely on 28undocumented features, then you should be able to re-compile it without 29modification with any later release x.y'.z' with the same major version 30number, and your code will still build, be secure, and work. 31 32Note that this guarantee only applies if you either use the default 33compile-time configuration (`mbedtls/config.h`) or the same modified 34compile-time configuration. Changing compile-time configuration options can 35result in an incompatible API or ABI, although features will generally not 36affect unrelated features (for example, enabling or disabling a 37cryptographic algorithm does not break code that does not use that 38algorithm). 39 40There are rare exceptions: code that was relying on something that became 41insecure in the meantime (for example, crypto that was found to be weak) may 42need to be changed. In case security comes in conflict with backwards 43compatibility, we will put security first, but always attempt to provide a 44compatibility option. 45 46For the LTS branches, additionally we try very hard to also maintain ABI 47compatibility (same definition as API except with re-linking instead of 48re-compiling) and to avoid any increase in code size or RAM usage, or in the 49minimum version of tools needed to build the code. The only exception, as 50before, is in case those goals would conflict with fixing a security issue, we 51will put security first but provide a compatibility option. (So far we never 52had to break ABI compatibility in an LTS branch, but we occasionally had to 53increase code size for a security fix.) 54 55For contributors, see the [Backwards Compatibility section of 56CONTRIBUTING](CONTRIBUTING.md#backwards-compatibility). 57 58## Backward compatibility for the key store 59 60We maintain backward compatibility with previous versions of the 61PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the 62storage backend (PSA ITS implementation) is configured in a compatible way. 63We intend to maintain this backward compatibility throughout a major version 64of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read 65keys written under any Mbed TLS 3.x with x <= y). 66 67Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x 68LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y) 69may require the use of an upgrade tool. 70 71## Current Branches 72 73The following branches are currently maintained: 74 75- [master](https://github.com/Mbed-TLS/mbedtls/tree/master) 76- [`development`](https://github.com/Mbed-TLS/mbedtls/) 77- [`mbedtls-2.28`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-2.28) 78 maintained until at least the end of 2024, see 79 <https://github.com/Mbed-TLS/mbedtls/releases/tag/v2.28.7>. 80 81Users are urged to always use the latest version of a maintained branch. 82