Skip to content

Commit 0a9d1eb

Browse files
committed
Adjust with suggested language from lavalamp
1 parent dd082f4 commit 0a9d1eb

File tree

1 file changed

+9
-7
lines changed

1 file changed

+9
-7
lines changed

contributors/devel/sig-architecture/api-conventions.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -364,13 +364,15 @@ Conditions are most useful when they follow some consistent conventions:
364364
("Deploying"). Intermediate states may be indicated by setting the status of
365365
the condition to `Unknown`.
366366

367-
* For state transitions which take a long period of time, use a condition
368-
which indicates that the transition succeeded ("Provisioned" or
369-
"SizeAllocated") with an intermediate state of `Unknown`. Note that this
370-
pattern makes an explicit distinction between "condition not set" (which
371-
means the reconciler hasn't seen the latest state) and "condition set to
372-
Unknown" (which means that the reconciler has seen the state but hasn't
373-
finished the reconciliation).
367+
* For state transitions which take a long period of time (rule of thumb: > 1
368+
minute), it is reasonable to treat the transition itself as an observed
369+
state. In these cases, the Condition (such as "Resizing") itself should not
370+
be transient, and should instead be signalled using the
371+
`True`/`False`/`Unknown` pattern. This allows other observers to determine
372+
the last update from the controller, whether successful or failed. In cases
373+
where the state transition is unable to complete and continued
374+
reconciliation is not feasible, the Reason and Message should be used to
375+
indicate that the transition failed.
374376

375377
* When designing Conditions for a resource, it's helpful to have a common
376378
top-level condition which summarizes more detailed conditions. Simple

0 commit comments

Comments
 (0)