That doesn't seem like the right doc fix. I would say "don't use strategic merge patch with this field" and explain why.

I think my current contribution makes it clearer that this information should not be taken as truth. Do you want me to add a part indicating "don't use strategic merge patch with this field" or replace my comment by yours ?
I think mine makes it clearer for those not necessarily familiar with merge strategies in k8s. WDYT ?

Other than a strategic merge patch or purely client-side confusion, is there any other way for this field to become “out of date”?

If the only API means to get it wrong are strategic merge patch, we can say so.
💭 We could also, in the API, send a Warning: response any time someone does a strategic merge patch that updates this field (and client-go etc then presents the warning to its caller).

I think my current contribution makes it clearer that this information should not be taken as truth.

But it is the truth. If you have a Service that is delivering to port "foo" on a given pod, and someone uses strategic merge patch and accidentally removes that entry from Ports, then the service will stop delivering traffic to that pod. The problem is not that Ports contains incorrect information; it's that the pod has been redefined, and the new definition isn't what you had wanted.

Sorry, I should have been clearer in my wording. Indeed you are right, it is the truth.

I don't think there's any other way of the fields Ports to be out-of-date.
I agree we should indicate the problem is using strategic merge patch in this case, but I would prefer if we also make it clear for people that are not familiar with it (as was I when I encountered this bug). Is it okay to link k8s docs in those comments ?
I would say something along the lines of

Use of strategic merge patch with this field can lead to errors due to information seemingly being the same but actually being different. This happens when applying diffing with arrays with same port number since the diffing takes only port into account and not the tuple (port, protocol).
See <link to the issue>
See <link to strategic merge patch like https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#notes-on-the-strategic-merge-patch>.

Sending a warning sounds like a great idea ! Do you mind giving me some pointers on how to do this ? Should I add this to this PR or should I make another one ?

I'm also open to suggestions on wording since I'm not a native english speaker.

The other case I know of is:

https://github.com/kubernetes/api/blob/v0.24.2/core/v1/types.go#L4986

But that's a field that end users don't really modify anyway (since kubelet would overwrite their modifications) so the docs don't need to worry as much about being understandable to end users...

Use of strategic merge patch with this field can lead to errors due to information seemingly being the same but actually being different. This happens when applying diffing with arrays with same port number since the diffing takes only port into account and not the tuple (port, protocol).

I'm not sure it's worth explaining in that much detail since it doesn't especially help the user to solve their problem. I'd just note that trying to modify it with strategic merge patch may corrupt the data, but that you can still use other kinds of patch if you need to. And link to this PR or to #108255 and then people who want to know more can follow the link.

Sending a warning sounds like a great idea ! Do you mind giving me some pointers on how to do this ? Should I add this to this PR or should I make another one ?

I opened #110627 about that, but it's likely to be complicated. I don't know exactly how the apiserver warning mechanism works...

I followed the issue as well. I'm not an expert in client-go / API server but I'm a bit worried on how the client will get an error properly.

Otherwise, thanks for the feedback, will update the PR.