docs: add Declarative Validation Native (DV Native) to api-conventions.md and api_changes.md

[aaron-prindle]

This PR updates the API development guidelines to include documentation for Declarative Validation Native (DV Native).

DV Native is a mode for the declarative validation framework that allows new API fields to use Declarative Validation (DV) exclusively, removing the need for parallel hand-written Go validation logic (speeding up dev and review! ⚡ ).

Changes:

• contributors/devel/sig-architecture/api_changes.md: Added a detailed section on DV Native covering:
  • The +k8s:declarativeValidationNative opt-in tag.
  • Stability level enforcement (requiring stable tags by default).
  • Required strategy changes using rest.WithDeclarativeNative().
  • Testing requirements using .MarkDeclarativeNative().
• contributors/devel/sig-architecture/api-conventions.md: Added a brief introduction and link to the DV Native documentation within the Validation section.

This PR is adapted from the dev-branch doc PR here:

• docs: add DV-NATIVE.md guide and document +k8s:declarativeValidationNative tag jpbetz/validation-gen#232

[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 assign dims for approval. 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

[dims]

/assign @liggitt

[liggitt]

it's a little unfortunate to have to add this to all DV-only fields for the future ... is there not a way to indicate this only in the strategy / tests and not need need to pollute the field docs with this?

[aaron-prindle]

/cc @lalitc375

[lalitc375]

Yes, it is possible to indicate this in the strategy.go files. This will tie our hands, forcing us to use only stable validations tags for that kind. This means we will not be able to use alpha/beta tags mirrored with handwritten validation code in that kind. 

Secondarily, Eventually we don't want to restrict DV native for new API's. We want to also enable DV native validations for new fields added to existing kinds. This gives us flexibility to do that. 

We hear your feedback. If a Kind only has all stable validations. They we just need to put this new tag on one super field i.e., spec. This will automatically mark all validations of the spec field and its subfields as native.  This should not pollute the Kind that much.

type MyType {

// +k8s:declarativeNativeValidation
Spec  MySpec

Status MyStatus
}

[liggitt]

1. Does the DV test framework prevent adding a DV validation without a covering test? If not, that seems like a good gap to close.

2. Are DV validation tests required to exercise in DV and non-DV mode OR explicitly indicate the validation it is testing is DV-native? If not, that seems like a good gap to close. If so, wouldn't we run DV-native tests with only stable DV validations enabled? That seems like it would cover what we need without requiring native-indication in the field docs.

[lalitc375]

Does the DV test framework prevent adding a DV validation without a covering test? If not, that seems like a good gap to close.

There are no tests to test this. This responsibility is on the reviewers right now. There is an AI prompt to make sure all DV tags have tests. https://github.com/gke-labs/gemini-for-kubernetes-development/blob/main/commands/dv/review.toml

Are DV validation tests required to exercise in DV and non-DV mode OR explicitly indicate the validation it is testing is DV-native? If not, that seems like a good gap to close. If so, wouldn't we run DV-native tests with only stable DV validations enabled? That seems like it would cover what we need without requiring native-indication in the field doc

Yes, DV validation tests required to exercise in DV and non-DV mode. We segregate native validations errors from all dv errors, there is a bool present in the error struct to indicate whether it is from a native validation or not. Test cases need to explicitly mention which type of validations errors they are expecting for a given failure scenario. Mismatches in this will result an test failure and leaks will be caught.

[liggitt]

There are no tests to test this.

That might be a good improvement to add to the backlog. If adding a DV tag couldn't merge until a test that exercised it was added, that would be ideal.

If so, wouldn't we run DV-native tests with only stable DV validations enabled? That seems like it would cover what we need without requiring native-indication in the field doc

Yes, DV validation tests required to exercise in DV and non-DV mode.

So... can we scope the DV-native indicator to the test definition that is exercising the specific test? That would skip running the non-DV version, and would run the DV version with only stable tags enabled, and make sure the tested validation still works? That seems like it would give similar granularity without needing to pollute the type docs

[aaron-prindle]

/hold
There is some discussion about the implementation and semantics for supporting DV tags w/ no HW counterpart. Will unhold or cancel this PR based on the resolution