[zep noup] 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,37 @@
+Scope of this document
+======================
+
+Explain how to update Zephyr's fork of Mbed TLS to align with a newer upstream
+release.
+This document talks about Mbed TLS, but the same guidelines apply to
+the other forks of the TF-M and Mbed TLS projects.
+
+Proposed approach
+=================
+
+Let's say that a new Mbed TLS release is announced and that its release tag
+is for example `v3.6.5`.
+On the Zephyr fork:
+1. Create a new branch named `zephyr_<project_name>_v<upstream_release_version>`
+   which is located exactly at the upstream release tag. For example,
+   `zephyr_mbedtls_v3.6.5`.
+2. Make a PR by cherry-picking all the Zephyr extra patches that are still needed
+   for the new branch.
+   - Discard all the `[zep fromtree]` and `[zep fromlist]` commits that are already
+      included in the release. As for `[zep noup]` they might no more be valid
+      or might require an update so they should be checked individually.
+   - The cherry-picking order should be: `[zep fromtree]` first, then
+       `[zep fromlist]` and finally `[zep noup]`.
+   - Cherry-pick commits without `-x` nor `-s` so as not to inflate the commit
+     message over time, unless you had to modify the commit and it's not just a
+     clean cherry-pick.
+3. For the created PR set the base branch to the newly-created one. In our example,
+   it would be `zephyr_mbedtls_v3.6.5`.
+   - With this approach the PR in GitHub will only show Zephyr's extra commits
+     on top of the upstream release tag, so it will be easier to review.
+4. Get the PR approved and merged.
+5. Make a PR in Zephyr repo to update the West revision of the Mbed TLS project.
+6. Set the repo default branch to `zephyr_mbedtls_v3.6.5`.
+   - When this is done, the HEAD of the previous default branch (which in our
+     example would be `zephyr_mbedtls_v3.6.4`) is tagged (in order to keep its
+     history) with the name same as the branch and the branch is removed.