Skip to content

doc: extend README explaining how version bumping should be handled #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: zephyr
Choose a base branch
from
Open

doc: extend README explaining how version bumping should be handled #78

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,3 +59,35 @@ This is for local patches that are not expected to make their way upstream.
This should be used sparingly and for good reasons, as we do not want to deviate from upstream. This is not meant as a quick way to get changes into this repository by bypassing upstream and such commits will be rejected.

`noup` commits are like regular commits in the main Zephyr repository with the exception that their commit title is prepended with `[zep noup]`.

Version bumping
---------------

This section talks about Mbed TLS, but the same guidelines apply to the other
forks of the TF-M and Mbed TLS projects.
Copy link
Member

@ceolin ceolin Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I particularly not a fan of creating a policy for another repository in here. I know most people working on TF-M are also working on MBED TLS but they are different projects. For me either it would be done in Zephyr's doc or in both projects. I think we should copy it there as well.

Copy link
Collaborator Author

@valeriosetti valeriosetti Nov 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#78 (comment)
#78 (comment)

I think @tomi-font would like to use this document as guide for few other modules (see also https://github.com/zephyrproject-rtos/tf-m-tests/pull/16/files). However since this guideline might not be super generic, he proposed to keep it confined to Mbed TLS and TF-M and not to go in Zephyr documentation.

Copy link
Collaborator

@tomi-font tomi-font Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point was exactly to have a single source of truth, and have the other relevant repos point to it. Maintaining copies of it is just extra duplication work and pretty much guaranteed to fall out of sync so I'm really not in favor of that.

And as @valeriosetti said IMO this is very specific to those repos and only affects people contributing to them so here just seems like the natural place for that.


Let's say that a new Mbed TLS release is announced and that its version is `3.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.
Copy link
Member

@ceolin ceolin Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't it possibly inflate only [zep noup] ? The others will come fresh from the list / tree and wouldn't make sense whoever is cherry picking them sign off ?

Copy link
Collaborator Author

@valeriosetti valeriosetti Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#78 (comment)
#78 (comment)

Copy link
Collaborator

@tomi-font tomi-font Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I proposed that because we have experience with this in NCS and it's just not nice and has no added value when you have a noup with 10 sign-offs and cherry picked from [...] lines. It gets messy and you don't even know anymore who contributed or modified the patch.

3. When creating the 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 in Mbed TLS fork approved and merged.
5. Set the new branch (in our example, `zephyr_mbedtls_v3.6.5`) as the default
branch of the repository.
- When this is done, tag the HEAD of the previous default branch (which in our
example would be `zephyr_mbedtls_v3.6.4`) with the name same as the branch
(in order to keep its history) and remove that branch.