Umbrella issue - API conventions, changes, review guidelines

liggitt commented 5 years ago

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 - https://github.com/kubernetes/community/issues/876
[ ] name length limit - https://github.com/kubernetes/community/issues/814
[ ] use of finalizers - https://github.com/kubernetes/community/issues/691
[ ] conventions for RAW API fields - https://github.com/kubernetes/community/issues/357
[ ] list of api_changes suggestions - https://github.com/kubernetes/community/issues/1297
[ ] overall developer guide improvements - https://github.com/kubernetes/community/issues/3064

hoisted from https://github.com/kubernetes/community/pull/5842#discussion_r778487246:

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 commented 5 years ago

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

liggitt commented 5 years ago

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

liggitt commented 5 years ago

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 commented 5 years ago

Promote RunAsGroup to beta review notes

thockin commented 5 years ago

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

thockin commented 5 years ago

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

thockin commented 5 years ago

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

liggitt commented 5 years ago

PSP RuntimeClass review

liggitt commented 5 years ago

volume expansion secret review

liggitt commented 5 years ago

windows GMSA review

liggitt commented 5 years ago

non-preempting priority classes review

liggitt commented 5 years ago

inline CSI migration review

ezzoueidi commented 5 years ago

I can help with this!

fejta-bot commented 4 years ago

Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale

fejta-bot commented 4 years ago

Stale issues rot after 30d of inactivity. Mark the issue as fresh with /remove-lifecycle rotten. Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle rotten