Umbrella issue - API conventions, changes, review guidelines

[liggitt]

This issue is to coordinate efforts to improve and add to the API conventions and API changes documentation, based on existing issues filed, and feedback from reviewers/shadows.

Questions encountered during designs/reviews (answer or clarify in existing docs):

• how should OS-specific fields be treated? should they be required to be empty or ignored when running on other OSes?

Issues encountered during code reviews (add guidance to relevant docs, or make more explicit if it already exists):

• don't increment storage version of a resource in the same release that introduces the new version (breaks HA upgrade)
• don't update callers that support version skew to older api servers (kubectl, controllers) to use new API versions in the same release where they are introduced
• when copying an existing resource to a new API group, update roles to permit the new API group as well

Checklists for developing and reviewing different types of API changes:

• New API group
• New resource
• New version of an existing resource
• New field in an existing resource (some guidance exists in API changes doc, ensure it is up to date)
• New allowed value in an enum field
• New value in a union type
• Tightening validation
• Relaxing validation

Items in the existing docs needing explanation or rationale

• ...

see also:

• PUT creating objects - API Conventions: PUT does not create new resource #876
• name length limit - API conventions should contain a maximum length for object names #814
• use of finalizers - API Conventions: Document use of finalizers #691
• conventions for RAW API fields - Document conventions for raw API fields #357
• list of api_changes suggestions - api_changes could be improved #1297
• overall developer guide improvements - Umbrella issue - Revamping the Kubernetes Developer’s guide #3064

hoisted from #5842 (comment):

• topic talking about reasons to use patch instead of read-modify-update:
  • avoid touching/dropping fields you don't know about
  • avoid precondition failures on rv if some other actor touched the object
• topic talking about how to use rv preconditions in conjunction with patch requests
• sweep existing "controllers" (including things like the kubelet) to see how they read from status fields of their objects to see if there are other patterns to follow or traps to avoid

[liggitt]

@kubernetes/sig-architecture-api-reviews @kubernetes/sig-api-machinery-api-reviews

[liggitt]

cc @kubernetes/api-approvers @kubernetes/api-reviewers
/assign

[liggitt]

API review log documents like the following are viewable by kubernetes-dev@googlegroups.com... join that mailing list for read access

Pod priority and preemption review notes

[liggitt]

Promote RunAsGroup to beta review notes

[thockin]

CSINodeInfo and CSIDriver notes: https://docs.google.com/document/d/1SBS0PqC0FlZ33LS4NtxGShBHsV-7waA6El5CnTFQre4/edit

[thockin]

CSI Inline Volumes: https://docs.google.com/document/d/19-q0YR6D1wuZwrdBl3U5Xp9Wg6d7UXPFXKvKv5uH96w/edit#

[thockin]

Ingress -> network group: https://docs.google.com/document/d/1RycD0x-WUBvPjtTyLYCZF_db_Jv9b36NW1PynMEOm9Q/edit

[liggitt]

PSP RuntimeClass review