API Linting Tracking Issue

[JoelSpeed]

As part of #11733, we have configured KAL, that kube-api-linter to run against the APIs within this repository.

There are a number of linter rules that need to be reviewed and enabled 1 by 1.

This issue is to track the implementation of enabling each of these linters

---

TODO

• conditions - 🌱 Enable the conditions rule from KAL #11847
• commentstart -
  • 🌱 Add comments for spec/status/items #11870
  • Related: Refactor godocs for API fields to start with the serialised versions #11238
• integers - 🌱 Enable integers lint of KAL #11887
• jsontags - 🌱 Enable jsontags lint of KAL #11890
• maxlength -
  • Enable the linter 🌱 enable maxlength linter #11906
  • Enable MaxItems ⚠️ Add MaxItems markers to API fields #11934
  • Enable MaxLength ⚠️ Add MaxLength & MinLength markers #11949
• nobools - 🌱 Enable nobools linter #11911
• nofloats - 🌱 Enable nofloats linter #11910
• optionalorrequired
  • Enable the linter 🌱 Enable optionalorrequired linter #11909
  • Follow-up for Items fields (exclude "field Items must be marked as optional or required")
• requiredfields - 🌱 Enable requiredfields linter #11908
• statussubresource - 🌱 Enable statussubresource linter #11907

---

Not doing

NoPhase

Per discussion in July 2024, we are keeping phase fields for now.
See #10897 (comment) and #10897 (comment) for the context on why we are still keeping phases.

[sivchari]

Hi @JoelSpeed
I'd work on this.
/assign

[JoelSpeed]

By all means! Just comment here before you pick up one of the rules to enable as between us I think we can open up the PRs in parallel for discussion

[sivchari]

I opened the PR for each linter to make it enabled

[tsuzu]

I'm working on commentstart linter in #11238 .
Let me assign assign myself.
/assign

[sbueringer]

All yours :) Thx for working on this

[sbueringer]

I think the last open task for now is

• Follow-up for Items fields (exclude "field Items must be marked as optional or required")

Given #11909 (comment), @JoelSpeed I'll assume you'll eventually get back to us and then we apply the marker accordingly (and/or adjust KAL).

I think otherwise we can close this issue.

I think it would be good to open a new issue, to track upcoming KAL linters so we have an overview on what we want to pick up going forward, WDYT?

[JoelSpeed]

Happy to either create that issue now or create issues as we get to them implemented in KAL. I expect it may take some time before we complete all of the requested KAL linters so opening an issue now may cause the issue to live for some time. I'm ok with that if you are though

[sbueringer]

I think let's go with:

create that issue now

I think the upside is that it gives some visiblity to the issues we are not yet linting for and thus have to focus a bit more on during API reviews.

(Also fine to move the Items topic from #11834 (comment) there)

[JoelSpeed]

Created #11967