eden-emu/mbedtls
15
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #4600 from gilles-peskine-arm/backward-compatibility-explanation-3.0

Browse source 
Document what we mean by backward compatibility
This commit is contained in:
Gilles Peskine 2021-06-09 10:40:30 +02:00 • committed by GitHub
commit cc0f250ea2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

34
BRANCHES.md
View file

@ -16,9 +16,10 @@ At any point in time, we have a number of maintained branches consisting of:
these only get bug fixes and security fixes. these only get bug fixes and security fixes.
We use [Semantic Versioning](https://semver.org/). In particular, we maintain We use [Semantic Versioning](https://semver.org/). In particular, we maintain
API compatibility in the `master` branch between major version changes. We API compatibility in the `master` branch across minor version changes (e.g.
also maintain ABI compatibility within LTS branches; see the next section for the API of 3.(x+1) is backward compatible with 3.x). We only break API
details. compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain
ABI compatibility within LTS branches; see the next section for details.
## Backwards Compatibility ## Backwards Compatibility
@ -28,11 +29,28 @@ undocumented features, then you should be able to re-compile it without
modification with any later release x.y'.z' with the same major version modification with any later release x.y'.z' with the same major version
number, and your code will still build, be secure, and work. number, and your code will still build, be secure, and work.
There are rare exceptions: code that was relying on something that became Note that new releases of Mbed TLS may extend the API. Here are some
insecure in the meantime (for example, crypto that was found to be weak) may examples of changes that are common in minor releases of Mbed TLS, and are
need to be changed. In case security comes in conflict with backwards not considered API compatibility breaks:
compatibility, we will put security first, but always attempt to provide a
compatibility option. * Adding or reordering fields in a structure or union.
* Removing a field from a structure, unless the field is documented as public.
* Adding items to an enum.
* Returning an error code that was not previously documented for a function
when a new error condition arises.
* Changing which error code is returned in a case where multiple error
conditions apply.
* 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.
There are rare exceptions where we break API compatibility: code that was
relying on something that became insecure in the meantime (for example,
crypto that was found to be weak) may need to be changed. In case security
comes in conflict with backwards compatibility, we will put security first,
but always attempt to provide a compatibility option.
## Long-time support branches
For the LTS branches, additionally we try very hard to also maintain ABI For the LTS branches, additionally we try very hard to also maintain ABI
compatibility (same definition as API except with re-linking instead of compatibility (same definition as API except with re-linking instead of