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