[KEP-3973]: document .status.terminatingReplicas enabled by DeploymentPodReplacementPolicy feature

content/en/docs/concepts/workloads/controllers/deployment.md

@@ -1327,6 +1327,19 @@ created Pod should be ready without any of its containers crashing, for it to be
 This defaults to 0 (the Pod will be considered available as soon as it is ready). To learn more about when
 a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
 
+### Terminating Pods
+
+{{< feature-state feature_gate_name="DeploymentPodReplacementPolicy" >}}
+
+You can enable this feature it by setting the `DeploymentPodReplacementPolicy`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+on the [API server](/docs/reference/command-line-tools-reference/kube-apiserver/)
+and on the [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume
+additional resources during that period. As a result, the total number of all pods can temporarily exceed
+`.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the Deployment.
+
 ### Revision History Limit
 
 A Deployment's revision history is stored in the ReplicaSets it controls.

content/en/docs/concepts/workloads/controllers/replicaset.md

@@ -320,6 +320,19 @@ To update Pods to a new spec in a controlled way, use a
 [Deployment](/docs/concepts/workloads/controllers/deployment/#creating-a-deployment), as
 ReplicaSets do not support a rolling update directly.
 
+### Terminating Pods
+
+{{< feature-state feature_gate_name="DeploymentPodReplacementPolicy" >}}
+
+You can enable this feature it by setting the `DeploymentPodReplacementPolicy`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+on the [API server](/docs/reference/command-line-tools-reference/kube-apiserver/)
+and on the [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume
+additional resources during that period. As a result, the total number of all pods can temporarily exceed
+`.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the ReplicaSet.
+
 ### Isolating Pods from a ReplicaSet
 
 You can remove Pods from a ReplicaSet by changing their labels. This technique may be used to remove Pods

content/en/docs/reference/command-line-tools-reference/feature-gates/deployment-pod-replacement-policy.md

@@ -0,0 +1,13 @@
+---
+title: DeploymentPodReplacementPolicy
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.33"
+---
+Enables a new status field `.status.terminatingReplicas` in Deployments and ReplicaSets to allow tracking of terminating pods.