blob: d9de6957d7256d71a982e526cc234d5048906ad0 [file] [log] [blame] [view]
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +01001# Maintained branches
2
3At any point in time, we have a number of maintained branches consisting of:
4
Gilles Peskine991bbe72021-03-16 12:05:16 +01005- The [`master`](https://github.com/ARMmbed/mbedtls/tree/master) branch:
6 this always contains the latest release, including all publicly available
7 security fixes.
Gilles Peskinea23df132021-03-16 12:04:44 +01008- The [`development`](https://github.com/ARMmbed/mbedtls/tree/development) branch:
Dave Rodgmana00e8502021-04-23 16:43:13 +01009 this is where the next major version of Mbed TLS (version 3.0) 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.
Gilles Peskinea23df132021-03-16 12:04:44 +010015- One or more long-time support (LTS) branches:
16 these only get bug fixes and security fixes.
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010017
18We use [Semantic Versioning](https://semver.org/). In particular, we maintain
Gilles Peskine991bbe72021-03-16 12:05:16 +010019API compatibility in the `master` branch between major version changes. We
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010020also maintain ABI compatibility within LTS branches; see the next section for
21details.
22
23## Backwards Compatibility
24
Gilles Peskinea23df132021-03-16 12:04:44 +010025We maintain API compatibility in released versions of Mbed TLS. If you have
26code that's working and secure with Mbed TLS x.y.z and does not rely on
27undocumented features, then you should be able to re-compile it without
28modification with any later release x.y'.z' with the same major version
29number, and your code will still build, be secure, and work.
30
Gilles Peskined1a8cd52021-06-07 20:42:40 +020031Note that new releases of Mbed TLS may extend the API. Here are some example of changes that are common in minor releases of Mbed TLS, and are not considered API compatibility breaks:
Gilles Peskine1483fe42021-06-01 22:29:06 +020032
33* Adding or reordering fields in a structure or union.
34* Removing a field from a structure, unless the field is documented as public.
35* Adding items to an enum.
36* Returning an error code that was not previously documented for a function when a new error condition arises.
37* Changing which error code is returned in a case where multiple error conditions apply.
38* Changing the behavior of a function from failing to succeeding, when the change is a reasonable extension of the current behavior, i.e. the addition of a new feature.
39
Gilles Peskined1a8cd52021-06-07 20:42:40 +020040There are rare exceptions where we break API compatibility: code that was
41relying on something that became insecure in the meantime (for example,
42crypto that was found to be weak) may need to be changed. In case security
43comes in conflict with backwards compatibility, we will put security first,
44but always attempt to provide a compatibility option.
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010045
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
Manuel Pégourié-Gonnard80c02af2021-02-25 12:34:58 +010055For contributors, see the [Backwards Compatibility section of
56CONTRIBUTING](CONTRIBUTING.md#cackwords-compatibility).
57
58## Current Branches
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010059
60The following branches are currently maintained:
61
Gilles Peskine991bbe72021-03-16 12:05:16 +010062- [master](https://github.com/ARMmbed/mbedtls/tree/master)
Gilles Peskinea23df132021-03-16 12:04:44 +010063- [`development`](https://github.com/ARMmbed/mbedtls/)
Dave Rodgmana00e8502021-04-23 16:43:13 +010064- [`development_2.x`](https://github.com/ARMmbed/mbedtls/tree/development_2.x)
Gilles Peskinea23df132021-03-16 12:04:44 +010065- [`mbedtls-2.16`](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.16)
Manuel Pégourié-Gonnard80c02af2021-02-25 12:34:58 +010066 maintained until at least the end of 2021, see
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010067 <https://tls.mbed.org/tech-updates/blog/announcing-lts-branch-mbedtls-2.16>
Manuel Pégourié-Gonnarde6997392021-02-25 11:40:08 +010068
69Users are urged to always use the latest version of a maintained branch.