Change:
// SharedInformer provides eventually consistent linkage of its // clients to the authoritative state of a given collection of // objects.  An object is identified by its API group, kind/resource, <del> // namespace, and name; the `ObjectMeta.UID` is not part of an // object's ID as far as this contract is concerned.  One </del> <ins> // namespace (if any), and name; the `ObjectMeta.UID` is not part of // an object's ID as far as this contract is concerned.  One </ins> // SharedInformer provides linkage to objects of a particular API // group and kind/resource.  The linked object collection of a <del> // SharedInformer may be further restricted to one namespace and/or by // label selector and/or field selector. </del> <ins> // SharedInformer may be further restricted to one namespace (if // applicable) and/or by label selector and/or field selector. </ins> // // The authoritative state of an object is what apiservers provide // access to, and an object goes through a strict sequence of states. <del> // An object state is either "absent" or present with a // ResourceVersion and other appropriate content. </del> <ins> // An object state is either (1) present with a ResourceVersion and // other appropriate content or (2) "absent". </ins> // <del> // A SharedInformer maintains a local cache, exposed by GetStore() and // by GetIndexer() in the case of an indexed informer, of the state of // each relevant object.  This cache is eventually consistent with the // authoritative state.  This means that, unless prevented by // persistent communication problems, if ever a particular object ID X // is authoritatively associated with a state S then for every // SharedInformer I whose collection includes (X, S) eventually either // (1) I's cache associates X with S or a later state of X, (2) I is // stopped, or (3) the authoritative state service for X terminates. // To be formally complete, we say that the absent state meets any // restriction by label selector or field selector. </del> <ins> // A SharedInformer maintains a local cache --- exposed by GetStore(), // by GetIndexer() in the case of an indexed informer, and possibly by // machinery involved in creating and/or accessing the informer --- of // the state of each relevant object.  This cache is eventually // consistent with the authoritative state.  This means that, unless // prevented by persistent communication problems, if ever a // particular object ID X is authoritatively associated with a state S // then for every SharedInformer I whose collection includes (X, S) // eventually either (1) I's cache associates X with S or a later // state of X, (2) I is stopped, or (3) the authoritative state // service for X terminates.  To be formally complete, we say that the // absent state meets any restriction by label selector or field // selector. </ins> // // For a given informer and relevant object ID X, the sequence of // states that appears in the informer's cache is a subsequence of the

Discussion:
<!-- Please use this template while reporting a bug and provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner. Thanks! If the matter is security related, please disclose it privately via --What happened: I discovered colleagues writing informer clients that modify objects delivered by informers. I went looking for where it says they should not do that, and I could not find it. What you expected to happen: I expected this critical restriction to be prominently documented. How to reproduce it (as minimally and precisely as possible): Try to find where it says that a client of an informer must not modify an object delivered by the informer. Anything else we need to know?: Environment: Kubernetes version (use ): Cloud provider or hardware configuration: OS (e.g: ): Kernel (e.g. ): Install tools: Network plugin and version (if this is a network-related bug): Others:
Documentation aside, I would suggest adding to your CI infra to make it harder for people to make this mistake.
/assign Thank you for fixing docs!