doc: add document to explain how version bumping should be handled

This commit introduces a document which describes how version bumping to
upstream Mbed TLS' releases should be handled in the Zephyr's fork of
Mbed TLS.

Signed-off-by: Valerio Setti <vsetti@baylibre.com>

Author: valeriosetti

version-bumping.md

@@ -0,0 +1,113 @@
+Scope of this document
+======================
+
+Explain how to update the Zephyr's fork of Mbed TLS to align with a newer
+upstream release.
+This document talks about Mbed TLS, but the very same applies also to
+TF-PSA-Crypto that, starting from Mbed TLS release 4.0, will be part of the
+Mbed TLS project.
+
+Upstream Mbed TLS branches and tags
+===================================
+
+- Working branch name: `development`
+- 1 or more LTS branches named as `mbedtls-<major>.<minor>` (ex: `mbedtls-3.6`)
+- Tag at every release with format `v<major>.<minor>.<patch>` (ex: `v3.6.4`)
+
+How was done in the past?
+=========================
+
+Zephyr's fork of Mbed TLS contains some extra patches that are not applied (and
+that won't be applied) upstream.
+
+So the procedure for each version bump was as follows:
+- revert all the Zephyr's additional patches;
+- merge all the changes from upstream Mbed TLS;
+- re-apply all Zephyr's additional patches.
+
+Graphically prior to each release we had:
+
+```
+* Mbed TLS commit #1
+* Mbed TLS commit #2
+* Mbed TLS commit #3 ("v3.6.3" tag)
+* Zephyr commit #1
+* Zephyr commit #2
+* Zephyr commit #3 ("zephyr" branch HEAD)
+```
+
+and then after it:
+
+```
+* Mbed TLS commit #1
+* Mbed TLS commit #2
+* Mbed TLS commit #3 ("v3.6.3" tag)
+* Zephyr commit #1
+* Zephyr commit #2
+* Zephyr commit #3
+* Revert Zephyr commit #3
+* Revert Zephyr commit #2
+* Revert Zephyr commit #1
+* Mbed TLS commit #4
+* Mbed TLS commit #5
+* Mbed TLS commit #6 ("v3.6.4" tag)
+* Zephyr commit #1
+* Zephyr commit #2
+* Zephyr commit #3 ("zephyr" branch HEAD)
+```
+
+Proposed approach
+=================
+
+Create a branch named `zephyr-development` that includes:
+
+- all Mbed TLS' commits on `development` branch up to a certain tag and
+- Zephyr's custom commits.
+
+Graphically:
+
+```
+* Mbed TLS commit #1
+* Mbed TLS commit #2
+* Mbed TLS commit #3 ("v3.6.3" tag)
+ \
+  * Zephyr commit #1
+  * Zephyr commit #2
+  * Zephyr commit #3 ("zephyr-development" branch HEAD)
+```
+
+All new Zephyr's patches go on top of `zephyr-development` HEAD.
+
+When a new Mbed TLS release is announced then:
+- current Zephyr's HEAD commit is tagged adding a `zephyr_` prefix to the
+  upstream Mbed TLS' tag;
+- rebase on the upstream tag of the new release.
+
+Graphically:
+
+```
+* Mbed TLS commit #1
+* Mbed TLS commit #2
+* Mbed TLS commit #3 (Mbed TLS tag #1 - ex: "v3.6.3")
+|\
+| * Zephyr commit #1
+| * Zephyr commit #2
+| * Zephyr commit #3 ("zephyr-v3.6.3" tag)
+|
+* Mbed TLS commit #4
+* Mbed TLS commit #5
+* Mbed TLS commit #6 (Mbed TLS tag #1 - ex: v3.6.4)
+|\
+| * Zephyr commit #1
+| * Zephyr commit #2
+| * Zephyr commit #3 ("zephyr-development" branch HEAD)
+```
+
+This last graph shows the ideal situation where all the Zephyr's commits still
+apply also on the new Mbed TLS release. This might not be the case because:
+- some Zephyr's patch might have been upstream upstreamed (so it's included
+  in Mbed TLS' commits) or
+- some new commit is required in order to fix compatibility between Zephyr
+  and Mbed TLS.
+
+In these cases the number of rebased commits might change as required.