Clarify EPSlice docs wrt the Ready conditions

`publishNotReadyAddresses` is an explicit override, so this makes it
clear that is OK.

api/openapi-spec/swagger.json

@@ -10162,7 +10162,7 @@
       "description": "EndpointConditions represents the current condition of an endpoint.",
       "properties": {
         "ready": {
-          "description": "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints.",
+          "description": "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints, except when the normal readiness behavior is being explicitly overridden, for example when the associated Service has set the publishNotReadyAddresses flag.",
           "type": "boolean"
         },
         "serving": {

api/openapi-spec/v3/apis__discovery.k8s.io__v1_openapi.json

@@ -103,7 +103,7 @@
         "description": "EndpointConditions represents the current condition of an endpoint.",
         "properties": {
           "ready": {
-            "description": "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints.",
+            "description": "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints, except when the normal readiness behavior is being explicitly overridden, for example when the associated Service has set the publishNotReadyAddresses flag.",
             "type": "boolean"
           },
           "serving": {

pkg/apis/discovery/types.go

@@ -112,7 +112,9 @@ type EndpointConditions struct {
 	// according to whatever system is managing the endpoint. A nil value
 	// indicates an unknown state. In most cases consumers should interpret this
 	// unknown state as ready. For compatibility reasons, ready should never be
-	// "true" for terminating endpoints.
+	// "true" for terminating endpoints, except when the normal readiness
+	// behavior is being explicitly overridden, for example when the associated
+	// Service has set the publishNotReadyAddresses flag.
 	Ready *bool
 
 	// serving is identical to ready except that it is set regardless of the

pkg/generated/openapi/zz_generated.openapi.go

@@ -28013,7 +28013,7 @@ func schema_k8sio_api_discovery_v1_EndpointConditions(ref common.ReferenceCallba
 				Properties: map[string]spec.Schema{
 					"ready": {
 						SchemaProps: spec.SchemaProps{
-							Description: "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints.",
+							Description: "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints, except when the normal readiness behavior is being explicitly overridden, for example when the associated Service has set the publishNotReadyAddresses flag.",
 							Type:        []string{"boolean"},
 							Format:      "",
 						},

staging/src/k8s.io/api/discovery/v1/generated.proto

@@ -86,7 +86,9 @@ message EndpointConditions {
   // according to whatever system is managing the endpoint. A nil value
   // indicates an unknown state. In most cases consumers should interpret this
   // unknown state as ready. For compatibility reasons, ready should never be
-  // "true" for terminating endpoints.
+  // "true" for terminating endpoints, except when the normal readiness
+  // behavior is being explicitly overridden, for example when the associated
+  // Service has set the publishNotReadyAddresses flag.
   // +optional
   optional bool ready = 1;
 

staging/src/k8s.io/api/discovery/v1/types.go

@@ -130,7 +130,9 @@ type EndpointConditions struct {
 	// according to whatever system is managing the endpoint. A nil value
 	// indicates an unknown state. In most cases consumers should interpret this
 	// unknown state as ready. For compatibility reasons, ready should never be
-	// "true" for terminating endpoints.
+	// "true" for terminating endpoints, except when the normal readiness
+	// behavior is being explicitly overridden, for example when the associated
+	// Service has set the publishNotReadyAddresses flag.
 	// +optional
 	Ready *bool `json:"ready,omitempty" protobuf:"bytes,1,name=ready"`
 

staging/src/k8s.io/api/discovery/v1/types_swagger_doc_generated.go

@@ -45,7 +45,7 @@ func (Endpoint) SwaggerDoc() map[string]string {
 
 var map_EndpointConditions = map[string]string{
 	"":            "EndpointConditions represents the current condition of an endpoint.",
-	"ready":       "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints.",
+	"ready":       "ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be \"true\" for terminating endpoints, except when the normal readiness behavior is being explicitly overridden, for example when the associated Service has set the publishNotReadyAddresses flag.",
 	"serving":     "serving is identical to ready except that it is set regardless of the terminating state of endpoints. This condition should be set to true for a ready endpoint that is terminating. If nil, consumers should defer to the ready condition.",
 	"terminating": "terminating indicates that this endpoint is terminating. A nil value indicates an unknown state. Consumers should interpret this unknown state to mean that the endpoint is not terminating.",
 }