Skip to content

Commit 051ccc1

Browse files
authored
align guidelines with the framework principles, remove bad example (#104)
1 parent 8d45db4 commit 051ccc1

1 file changed

Lines changed: 11 additions & 25 deletions

File tree

‎docs/guidelines.md‎

Lines changed: 11 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -621,34 +621,20 @@ treated as disabled (resources deleted), not suspended (resources scaled down).
621621

622622
## Mutations Describe Intent, Not Observation
623623

624-
Mutations operate on the desired object, not the server's current state. If you need to make decisions based on the
625-
resource's live state in the cluster, use a data extractor to observe it and feed the result into a mutation through a
626-
closure variable.
624+
Mutations operate on the desired object, not the server's current state. A mutation should be a pure function of the
625+
owner spec and other static inputs available at build time. It should never try to read the resource's live cluster
626+
state to decide what to write.
627627

628-
```go
629-
var currentReplicas int32
628+
This is not just a style preference. Within a single resource, the framework runs mutations **before** data extraction.
629+
A data extractor registered on the same builder as a mutation will not have executed yet when that mutation runs. Any
630+
closure variable populated by the extractor will still hold its zero value.
630631

631-
res, _ := deployment.NewBuilder(baseline).
632-
WithDataExtractor(func(d appsv1.Deployment) error {
633-
currentReplicas = d.Status.ReadyReplicas
634-
return nil
635-
}).
636-
WithMutation(deployment.Mutation{
637-
Name: "scale-aware-annotation",
638-
Mutate: func(m *deployment.Mutator) error {
639-
m.EditPodTemplateMetadata(func(meta *editors.ObjectMetaEditor) error {
640-
meta.EnsureAnnotation("app.example.com/last-known-ready",
641-
fmt.Sprintf("%d", currentReplicas))
642-
return nil
643-
})
644-
return nil
645-
},
646-
}).
647-
Build()
648-
```
632+
Data extractors exist to pass observed state from an **earlier** resource to a **later** resource's guards and
633+
mutations. They are not a mechanism for feeding a resource's own live state back into its own mutations. If you find
634+
yourself wanting to do that, reconsider the design: the mutation is likely encoding observation rather than intent.
649635

650-
This keeps mutations predictable: they always produce the same desired state for the same inputs, regardless of what
651-
currently exists in the cluster, which aligns with Server-Side Apply's declarative model.
636+
A well-written mutation produces the same desired state for the same owner spec, regardless of what currently exists in
637+
the cluster. This aligns with Server-Side Apply's declarative model and keeps the reconciliation loop predictable.
652638

653639
## Understand Participation Modes
654640

0 commit comments

Comments
 (0)