🌱 Refactor godoc for API fields starting with field names

[tsuzu]

What this PR does / why we need it:

• This PR fixes all field starting with field names to serialized names specified as json tag.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
This is a part of #11238

/area api

[k8s-ci-robot]

Hi @tsuzu. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[neolit123]

i disagree with

• Refactor godocs for API fields to start with the serialised versions #11238

because it disagrees with how Go linters suggest comments for exported objects should be. k8s is quite inconsistent about its Go comments.

[JoelSpeed]

Across kube, the godocs that we write on API fields become generated documentation for end users, sometimes in API references, sometimes via kubectl explain (which you can do on any field in any resource).

If we use the serialised version, then the field description will consistently start with the name of the field as it appears in the yaml, that the user interacts with. If we refer to fields by the Go standard, then the field name will not match what the user interacts with. Most of the time, this is just the case of capitalisation differences, but there are occasions where the serialised and Go field names differ by more than that.

k8s is quite inconsistent about its Go comments.

Looking through the core v1 APIs, the majority are actually following the pattern we are suggesting here. There are some exceptions where random fields are with capitals (like Go would expect) and some where they don't even start with the name at all, so fit neither convention.

When these APIs were written, the conventions were still being formulated. It's natural that there will be inconsistencies from the early days that haven't been fixed, or the odd occasion where a field was missed during review, but if you were to run an API through a core Kube API review now, all of the current reviewers would enforce this standard.

We are writing them with the serialised form to make this easier for the user, as is with most conventions.

[sbueringer]

Makes sense to me. For what it's worth over the last few years when reviewing PRs I also tried to enforce that we always refer to fields via the "user-facing" names in error messages and logs.

[tsuzu]

The rule that comments should start with field names was enforced by golint, but it's archived.
Now it's also available with staticcheck, but disabled by default: https://staticcheck.dev/docs/checks/#ST1022

so I think that the rule may not be typical nowadays.

[sbueringer]

Let's revert the changes to the kubeadm upstream types, regenerate CRDs and then merge directly

[sbueringer]

Let's not change the vendored upstream types in upstreamv1beta*

[sbueringer]

/ok-to-test

[sbueringer]

@tsuzu please run 'make generate-manifests generate-go-openapi'

[sbueringer]

Thx!

/lgtm
/approve

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: d9810fbcab19cd52c4340432d0ab3f95ddbb080f

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sbueringer

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [sbueringer]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment