Change:
<!-- 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!

Discussion:
} } <del> // ResourceEventHandler can handle notifications for events that happen to a // resource. The events are informational only, so you can't return an // error. </del> <ins> // ResourceEventHandler can handle notifications for events that // happen to a resource. The events are informational only, so you // can't return an error.  The handlers MUST NOT modify the objects // received; this concerns not only the top level of structure but all // the data structures reachable from it. </ins> //  * OnAdd is called when an object is added. //  * OnUpdate is called when an object is modified. Note that oldObj is the //      last known state of the object-- it is possible that several changes

// ResourceEventHandlerFuncs is an adaptor to let you easily specify as many or // as few of the notification functions as you want while still implementing <del> // ResourceEventHandler. </del> <ins> // ResourceEventHandler.  This adapter does not remove the prohibition against // modifying the objects. </ins> type ResourceEventHandlerFuncs struct { AddFunc    func(obj interface{}) UpdateFunc func(oldObj, newObj interface{})

// in, ensuring the appropriate nested handler method is invoked. An object // that starts passing the filter after an update is considered an add, and an // object that stops passing the filter after an update is considered a delete. <ins> // Like the handlers, the filter MUST NOT modify the objects it is given. </ins> type FilteringResourceEventHandler struct { FilterFunc func(obj interface{}) bool Handler    ResourceEventHandler

// 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

// added before `Run()`, eventually either the SharedInformer is // stopped or the client is notified of the update.  A client added // after `Run()` starts gets a startup batch of notifications of <del> // additions of the object existing in the cache at the time that </del> <ins> // additions of the objects existing in the cache at the time that </ins> // client was added; also, for every update to the SharedInformer's // local cache after that client was added, eventually either the // SharedInformer is stopped or that client is notified of that