[zep noup] document the additional patches

[tomi-font]

Replace the upstream README with guidelines for the additional patches.

Documentation preview: https://github.com/tomi-font/zephyr-mbedtls/tree/repo_maintenance_guidelines?tab=readme-ov-file#additional-patches

[wearyzen]

Few questions:

• Does this mean every commit in the modules should have 1 of the 4 mentioned tags?
• Do we expect the fromlist commits to be reverted and swapped with fromtree commits once they are merged upstream?
• Could we consider no tag as fromtree to avoid editing the upstream cherry-picked commits?

[dleach02]

@wearyzen this tagging process is something Marti came up with in Founderies and brought to Nordic. The general objective though should be a minimal amount of downstream patches being maintained and managed. To answer your questions though> Few questions:

• Does this mean every commit in the modules should have 1 of the 4 mentioned tags?

Yes, all commits that are not part of sync/merge from the upstream shall have a tag to identify them as "Zephyr Project" additions.

• Do we expect the fromlist commits to be reverted and swapped with fromtree commits once they are merged upstream?
• Could we consider no tag as fromtree to avoid editing the upstream cherry-picked commits?

These questions are actually a larger question of what process is used for cleanup. When you have fromlist/fromtree tags, they imply commits that will eventually be pulled into the Zephyr fork with some later update. So how we clean these up are important.

I will also add that toup should be either never used or sparingly used. If you already know a change is something you want to submit to the upstream then for technical debt reasons, go ahead and submit a PR to the upstream and then use fromlist/fromtree to cherry-pick back. Otherwise, you are just submitting a commit to the downstream and then later you are going to submit a PR to the upstream. Let the clean-up process address things later.

@tomi-font do you want to articulate the synchronization and clean up process? I know that @d3zd3z does not want a revert/reapply process. I can think of other methods we can do for a module that doesn't include that flow which might be similar to how we do it now, although I'm not aware of how we have been doing it?

[d3zd3z]

Just some minor comments, otherwise looks good.

[d3zd3z]

So, technically, at least per Linux rules, a sign-off is required by anyone who cherry picks the patch. Given the overall project is under the LF, I suspect this rule would still apply here.

[tomi-font]

I'm not sure it necessary applies just by inheritance from Linux. I proposed no sign-off because to me it doesn't add any value, but all we really care about here is to agree on and enforce one way of doing, so I'm good with either.

[dleach02]

I tend to agree with @tomi-font here. We can set our own rules here and refer to other project for guidance/inspiration.

[d3zd3z]

I might be worth noting that 'fromlist' is historical, and this applies to changes living as PRs. It might be worth spelling out that Gerrit review is also a possibility.

[d3zd3z]

Perhaps describe how to reference in-review Gerrit patches as well, that would let us just use this same document across tf-m, etc.

[tomi-font]

Do we expect the fromlist commits to be reverted and swapped with fromtree commits once they are merged upstream?

To me no, except in the exceptional case where the commit merged upstream would turn out to have differences with the fromlist that was cherry picked and for some reason those changes are needed before the next update. In that case you would open a PR to do that but otherwise it's just additional unneeded burden.

Could we consider no tag as fromtree to avoid editing the upstream cherry-picked commits?

I'm not very fond of that idea. The tags make it very easy and fast to recognize patches (and their types), for commits without tags I would feel the need to check the commit message and maybe even more. Also, how about the case where the first commits in this repo are fromtrees (which is how we typically order them when updating)? Now you have to chase down what is the latest upstream commit and what is the first fromtree. Plus taking into consideration that upstream commits might themselves be cherry picks (from other branches)...

[tomi-font]

@tomi-font do you want to articulate the synchronization and clean up process? I know that @d3zd3z does not want a revert/reapply process. I can think of other methods we can do for a module that doesn't include that flow which might be similar to how we do it now, although I'm not aware of how we have been doing it?

I could take a stab at it, I'm also in favor of dropping the revert approach.

[wearyzen]

Thanks for the clarification! I initially misunderstood and thought this tagging process applied to all commits, including the initial ones used to sync with the latest upstream. Apart from adding some guidance for sync/cleanup process, the rest looks looks good to me as well.

[tomi-font]

I will also add that toup should be either never used or sparingly used. If you already know a change is something you want to submit to the upstream then for technical debt reasons, go ahead and submit a PR to the upstream and then use fromlist/fromtree to cherry-pick back. Otherwise, you are just submitting a commit to the downstream and then later you are going to submit a PR to the upstream. Let the clean-up process address things later.

I'm actually a bit undecided on the toup. The reason I included it is for legit cases where the commit might be available upstream (either in a PR or merged) but cannot be cherry picked as-is because of conflicts that cannot be resolved by just cherry picking some more upstream commits (or can but which would bring unacceptable changes).
Basically I meant the toup to be a noup that is expected to be dropped.
Maybe another acceptable scenario would be if we know that upstream is working on something, in which case it might be useless to submit a change upstream if it's taken care of by someone else as part of bigger changes.
It's really not meant as a way for someone to go downstream first.
In essence those commits could also be marked as noup, but I thought maybe it would be good to make the distinction with a different tag.

What do y'all think about this?

[tomi-font]

Updated according to comments and replaced toup by fromup which maybe better conveys the meaning.

[tomi-font]

@tomi-font do you want to articulate the synchronization and clean up process? I know that @d3zd3z does not want a revert/reapply process. I can think of other methods we can do for a module that doesn't include that flow which might be similar to how we do it now, although I'm not aware of how we have been doing it?

I could take a stab at it, I'm also in favor of dropping the revert approach.

Turns out @valeriosetti will propose something as a separate PR.

[frkv]

Generally LGTM

[valeriosetti]

@tomi-font do you want to articulate the synchronization and clean up process? I know that @d3zd3z does not want a revert/reapply process. I can think of other methods we can do for a module that doesn't include that flow which might be similar to how we do it now, although I'm not aware of how we have been doing it?

I could take a stab at it, I'm also in favor of dropping the revert approach.

Turns out @valeriosetti will propose something as a separate PR.

#78

[tomi-font]

According to feedback I replaced fromup by dirty fromtree/fromlist. Please have a look.

[Vge0rge]

So the structure here will be:

Original commit message
Original signoff
Commit message regarding the dirty cherry pick
Cherry pick signoff?

[tomi-font]

Correct.

[Vge0rge]

Then its all good, I was thinking if it makes sense to add something to distinguish the cherry pick message but since it will be placed after the original signoff it should be visible enough.

[dleach02]

I see that toup went completely away. I think you should consider still having it but document it as "to be used sparingly... try posting a PR upstream and cherry-picking it back". But there might be cases where we need to apply a patch that we want to submit upstream but for undetermined reasons we can't yet...

[ceolin]

I see that toup went completely away. I think you should consider still having it but document it as "to be used sparingly... try posting a PR upstream and cherry-picking it back". But there might be cases where we need to apply a patch that we want to submit upstream but for undetermined reasons we can't yet...

I tend to agree here. I can see a hot fix needed being submitted here before making it upstream. There should be all sorts of discouragements to this type of commit, but we should still cover it IMHO.

[tomi-font]

So what you both are talking about would now be covered by a noup.
The reason why I originally added toup/fromup was mostly just to cover the case of dirty cherry picks which definitely happens.
But then after some discussion with @Vge0rge I changed that to just making variants of fromtree/fromlist because that's essentially what they are.
We can handle temporary patches to this repo just as well with individual noup commits, so now that we have dirty cherry picks handled it seems there isn't much use for a separate toup tag?

[ceolin]

So what you both are talking about would now be covered by a noup. The reason why I originally added toup/fromup was mostly just to cover the case of dirty cherry picks which definitely happens. But then after some discussion with @Vge0rge I changed that to just making variants of fromtree/fromlist because that's essentially what they are. We can handle temporary patches to this repo just as well with individual noup commits, so now that we have dirty cherry picks handled it seems there isn't much use for a separate toup tag?

I think toup is more clear but I don't die for it.