Document how clients should use list/watch and resource versions

[jpbetz]

The Kubernetes docs need to explain how clients should properly use list/watch and handle resourceVersions, dropped watches, etc.

It should be sufficient high level guidance to implement a client in a new language.

https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions explains the resourceVersions rigorously, but does not explain HOW to use resourceVersions to implement list/watch.

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[jpbetz]

@BenTheElder @Jefftree any interest on working on this or finding a contributor to help?

[BenTheElder]

In parallel threads about this there seems to be quite a bit of debate still, I'm hesitant to attempt to write this one yet.

I definitely think this needs doing, and I might be prepared to help down the line.

[lmktfy]

@jpbetz / @BenTheElder your role could be to provide technical review for an evergreen (long term maintained) blog article. If we take that route, anyone can lead the work to write it.

We can confidently hyperlink to evergreen articles from our docs. For example: to
https://kubernetes.io/blog/2020/09/03/warnings/

[Okabe-Junya]

/sig docs
/priority important-longterm

[BenTheElder]

your role could be to provide technical review for an evergreen (long term maintained) blog article. If we take that route, anyone can lead the work to write it.

The problem I have is I'm seeing unclear agreement amongst contributors to this code, I think we need to drive consensus in API machinery before we can document it 😅