add notes about misunderstandings

Author: atiratree

keps/sig-apps/2804-consolidate-workload-controllers-status/README.md

@@ -87,12 +87,13 @@ tags, and then generate with `hack/update-toc.sh`.
     - [Story 1](#story-1)
     - [Story 2](#story-2)
   - [Overview of all conditions](#overview-of-all-conditions)
-  - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
+  - [Proposed Conditions](#proposed-conditions)
     - [Progressing](#progressing)
     - [Complete](#complete)
     - [Failed](#failed)
     - [Available](#available)
     - [Batch Workloads Conditions: Waiting & Running](#batch-workloads-conditions-waiting--running)
+  - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
   - [Risks and Mitigations](#risks-and-mitigations)
 - [Design Details](#design-details)
   - [Test Plan](#test-plan)
@@ -279,7 +280,7 @@ The following table gives an overview on what conditions each of the workload re
 
 **\*\* CronJob does not even have Conditions field in its Status**
 
-### Notes/Constraints/Caveats (Optional)
+### Proposed Conditions
 
 <!--
 What are the caveats to the proposal?
@@ -359,6 +360,14 @@ Kubernetes marks a Job as `running` if there is at least one Pod with phase `Run
 This KEP does not introduce CronJob conditions as it is difficult to define conditions that would describe CronJob behaviour in useful manner.
 In case the user is interested if there are any running Jobs, `.status.active` field should be sufficient.
 
+### Notes/Constraints/Caveats (Optional)
+
+As observed in some issues (https://github.com/kubernetes/website/pull/31226) and talking to the users, there is a misunderstanding about the meaning of the `Progressing` condition. These include:
+- Thinking that the `Progressing` condition reflects the state of the current Deployment instead of the last rollout. Which includes expectation that the `Progressing` condition will keep checking availability of replicas and revert to `progressing`/`failed` state even after the `complete` state is reached. And that the progressing condition will thus also reflect any changes in scaling.
+- Confusion that ProgressDeadlineExceeded does not occur after the Deployment rollout completes when the availability of pods degrades before the  `.spec.progressDeadlineSeconds` times out.
+
+To summarize, the name of the `Progressing` condition doesn't indicate its true meaning that its main responsibility is the indication of rollouts, and it confuses the users.
+
 ### Risks and Mitigations
 
 <!--