From 1483fe4c217786f530fda73931738a9a75d5d8a9 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 1 Jun 2021 22:29:06 +0200 Subject: [PATCH 1/5] Document what we mean by backward compatibility Signed-off-by: Gilles Peskine --- BRANCHES.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/BRANCHES.md b/BRANCHES.md index 8486ef0637..dbdc1738e4 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -28,6 +28,15 @@ 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 number, and your code will still build, be secure, and work. +Note 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 compatibility breaks: + +* 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: 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 From d1a8cd5169d81308be85320ad39c80ea810970a7 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 7 Jun 2021 20:42:40 +0200 Subject: [PATCH 2/5] Minor clarifications Signed-off-by: Gilles Peskine --- BRANCHES.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/BRANCHES.md b/BRANCHES.md index dbdc1738e4..d9de6957d7 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -28,7 +28,7 @@ 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 number, and your code will still build, be secure, and work. -Note 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 compatibility breaks: +Note 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: * Adding or reordering fields in a structure or union. * Removing a field from a structure, unless the field is documented as public. @@ -37,11 +37,11 @@ Note that new releases of Mbed TLS may extend the API. Here are some example of * 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: 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. +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. For the LTS branches, additionally we try very hard to also maintain ABI compatibility (same definition as API except with re-linking instead of From 87d36e311bd043ce4170f31c94803fc05b4c312b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 7 Jun 2021 20:42:50 +0200 Subject: [PATCH 3/5] Add a section heading for LTS branches Signed-off-by: Gilles Peskine --- BRANCHES.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/BRANCHES.md b/BRANCHES.md index d9de6957d7..a758d08b34 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -28,7 +28,7 @@ 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 number, and your code will still build, be secure, and work. -Note 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: +Note that new releases of Mbed TLS may extend the API. Here are some examples of changes that are common in minor releases of Mbed TLS, and are not considered API compatibility breaks: * Adding or reordering fields in a structure or union. * Removing a field from a structure, unless the field is documented as public. @@ -43,6 +43,8 @@ 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 compatibility (same definition as API except with re-linking instead of re-compiling) and to avoid any increase in code size or RAM usage, or in the From 6dd92c3f6b2c3e2dc28d966607560b260a491e27 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 7 Jun 2021 20:44:47 +0200 Subject: [PATCH 4/5] Wrap lines in the source to <80 columns Signed-off-by: Gilles Peskine --- BRANCHES.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/BRANCHES.md b/BRANCHES.md index a758d08b34..df30ae1004 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -28,14 +28,20 @@ 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 number, and your code will still build, be secure, and work. -Note that new releases of Mbed TLS may extend the API. Here are some examples of changes that are common in minor releases of Mbed TLS, and are not considered API compatibility breaks: +Note that new releases of Mbed TLS may extend the API. Here are some +examples of changes that are common in minor releases of Mbed TLS, and are +not considered API compatibility breaks: * 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. +* 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, From 73876cf9cb16ab8ca9c761ae9204692b0f626477 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 8 Jun 2021 15:33:53 +0200 Subject: [PATCH 5/5] Clarify "between major version changes" This was diversely interpreted as "compatibility in the period between two major version changes" (as intended) or "compatibility between two versions whose major version is different" (unintended). Signed-off-by: Gilles Peskine --- BRANCHES.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/BRANCHES.md b/BRANCHES.md index df30ae1004..b9926ac9df 100644 --- a/BRANCHES.md +++ b/BRANCHES.md @@ -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. We use [Semantic Versioning](https://semver.org/). In particular, we maintain -API compatibility in the `master` branch between major version changes. We -also maintain ABI compatibility within LTS branches; see the next section for -details. +API compatibility in the `master` branch across minor version changes (e.g. +the API of 3.(x+1) is backward compatible with 3.x). We only break API +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