docs: add documentation for adding a new API fields with validation using DV tags only and testing

[aaron-prindle]

This updates api_changes.md with a prescriptive section for the CUJ: “add a new API field and validate it with declarative validation”. It documents the DV plumbing prerequisites, DV tag authoring, feature gate and strategy wiring, codegen checks, status subresource handling, current workarounds like +k8s:validation-gen-nolint, and copy-paste snippets + testing guidance for declarative_validation_test.go and strategy_test.go.

Which issue(s) this PR fixes:

Fixes #
N/A

[aaron-prindle]

/cc @yongruilin @lalitc375

[aaron-prindle]

/assign @thockin

[yongruilin]

Do we prefer handwritten if part of the validation on the same field can be DV?

[aaron-prindle]

Yes, my understanding from our last sync meeting on Friday is that API reviewers want new APIs fields validation to be all DV or no DV for the validations of a given new field.

[aaron-prindle]

Updated the text to be:

If DV can cover some of the new field's checks but cannot cover all of them,
prefer handwritten validation for that field rather than splitting one field's
checks between DV and handwritten validation.

[yongruilin]

It is straightforward for adding a "new API type". But a bit tricky when it comes to a new API field:
If this type already migrated some existing fields to DV. Do we still support? Once the strategy add the WithDeclarativeEnforcement(), non-prefixed tag would become authoritative and handwritten counterpart needs to be deleted; otherwise, the migrated fields need to add the k8s:beta(or alpha?) prefix to enable explicitly shadowing.

[aaron-prindle]

I clarified the scope of this section with an additional small paragraph around this

This guidance assumes the API type is plumbed for declarative
validation. If the type already has existing DV migrated/shadowed fields (+k8s:alpha/+k8s:beta) and still relies on fields w/ handwritten validation and/or shadowed DV, those older fields can continue to
exist as-is, but do not introduce that split for the new field covered by this
section.

[yongruilin]

The last case, gate off, old value changed on update, we should have a fobidden error right? I think we can extend this a bit about what should be the expected test result.

[aaron-prindle]

I updated the test guidance to make the expected result explicit. Now is a table:

Case	Expected result
gate on, field specified	Allowed if the value is valid.
gate on, field omitted	Allowed.
gate on, invalid value specified	Rejected with the field's normal validation error, such as NotSupported, Invalid, TooLong, or TooMany.
gate off, field specified	Rejected. With the standard ifDisabled(...)=+k8s:forbidden pattern, expect a forbidden error.
gate off, field omitted	Allowed.
gate off, old value unchanged on update	Allowed due to ratcheting.
gate off, old value changed on update	Rejected. With the standard ifDisabled(...)=+k8s:forbidden pattern, expect a forbidden error because the update is attempting to write a disabled field value.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: aaron-prindle
Once this PR has been reviewed and has the lgtm label, please ask for approval from thockin. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• contributors/devel/sig-architecture/OWNERS

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