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/ARMmbed/mbedtls/tree/master) branch: 6 this always contains the latest release, including all publicly available 7 security fixes. 8- The [`development`](https://github.com/ARMmbed/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- The [`development_2.x`](https://github.com/ARMmbed/mbedtls/tree/development_2.x) branch: 13 this branch retains the API of Mbed TLS 2.x, and has a subset of the 14 features added after Mbed TLS 2.26.0 and bug fixes and security fixes. 15- One or more long-time support (LTS) branches: 16 these only get bug fixes and security fixes. 17 18We use [Semantic Versioning](https://semver.org/). In particular, we maintain 19API compatibility in the `master` branch across minor version changes (e.g. 20the API of 3.(x+1) is backward compatible with 3.x). We only break API 21compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain 22ABI compatibility within LTS branches; see the next section for details. 23 24## Backwards Compatibility 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 new releases of Mbed TLS may extend the API. Here are some 33examples of changes that are common in minor releases of Mbed TLS, and are 34not considered API compatibility breaks: 35 36* Adding or reordering fields in a structure or union. 37* Removing a field from a structure, unless the field is documented as public. 38* Adding items to an enum. 39* Returning an error code that was not previously documented for a function 40 when a new error condition arises. 41* Changing which error code is returned in a case where multiple error 42 conditions apply. 43* Changing the behavior of a function from failing to succeeding, when the 44 change is a reasonable extension of the current behavior, i.e. the 45 addition of a new feature. 46 47There are rare exceptions where we break API compatibility: code that was 48relying on something that became insecure in the meantime (for example, 49crypto that was found to be weak) may need to be changed. In case security 50comes in conflict with backwards compatibility, we will put security first, 51but always attempt to provide a compatibility option. 52 53## Long-time support branches 54 55For the LTS branches, additionally we try very hard to also maintain ABI 56compatibility (same definition as API except with re-linking instead of 57re-compiling) and to avoid any increase in code size or RAM usage, or in the 58minimum version of tools needed to build the code. The only exception, as 59before, is in case those goals would conflict with fixing a security issue, we 60will put security first but provide a compatibility option. (So far we never 61had to break ABI compatibility in an LTS branch, but we occasionally had to 62increase code size for a security fix.) 63 64For contributors, see the [Backwards Compatibility section of 65CONTRIBUTING](CONTRIBUTING.md#cackwords-compatibility). 66 67## Current Branches 68 69The following branches are currently maintained: 70 71- [master](https://github.com/ARMmbed/mbedtls/tree/master) 72- [`development`](https://github.com/ARMmbed/mbedtls/) 73- [`development_2.x`](https://github.com/ARMmbed/mbedtls/tree/development_2.x) 74- [`mbedtls-2.16`](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.16) 75 maintained until at least the end of 2021, see 76 <https://tls.mbed.org/tech-updates/blog/announcing-lts-branch-mbedtls-2.16> 77 78Users are urged to always use the latest version of a maintained branch. 79