Tracking issue for one breaking wave on GitTarget. Design:
docs/layout/api-wave.md (lands with #318; it was
docs/design/gittarget-api-wave.md).
What changed since this was filed
The wave lost its centrepiece and gained a deletion. spec.layout was reversed — #319 made
kustomization registration an invariant, which retired three of the five arguments against path
templates, so the template stays and gains two additive fields instead
(docs/layout/model.md, #293). The placement work is no
longer breaking at all.
Three items have since been dropped or added:
spec.mode: Observe|Write — dropped. Over a suspended target it bought only the difference
between a pause and a declared posture. A suspended target that keeps scanning and publishing
status.placement is the same adoption dry run with one field instead of two. suspend must
keep observing, which deviates from Flux, where suspend stops reconciliation altogether; that
goes in the field's docs.GitTarget.spec.interval — dropped. Every input that changes what a scan would conclude
arrives as an event, on a watch. Flux polls because a Git remote cannot be watched, which is
exactly why GitProvider.spec.interval stays. The residual gap (a folder someone else edits
while we write nothing) is covered on demand by the reconcile-request annotation.- The source-scope simplification — added. It deletes
GitTarget.spec.allowedSourceNamespaces, so it breaks the same object B4 breaks and must ride
the same bump. It is also the only member that makes the API smaller
(docs/design/source-scope-simplification.md).
Why one wave rather than several changes
The consumer pins us three ways (image, Go module, require line), so each breaking release costs a
coordinated bump. That argues for batching, and it is the weaker half of the argument.
The stronger half survives in reduced form: several of these items are the same design decision seen
from different angles, and building them separately means deciding it several times, inconsistently.
The folder is described on the GitTarget. The connection describes only the connection.
spec.suspend says whether we write to the folder.commitWindow and commit.message say how writes to it are batched and phrased, and today they
live on GitProvider, which is the connection.serializeNamespace and kustomizeRoot say what the documents in it look like — and these are
additive, so they ship without a bump.
Contents
Version stays v1alpha3: loud rejection of removed fields for one release, rather than paying for a
conversion path. The scope: Namespaced status-write envtest (F9) runs before any of this is
planned, because its answer constrains the enum work.
Tracking issue for one breaking wave on
GitTarget. Design:docs/layout/api-wave.md(lands with #318; it wasdocs/design/gittarget-api-wave.md).What changed since this was filed
The wave lost its centrepiece and gained a deletion.
spec.layoutwas reversed — #319 madekustomization registration an invariant, which retired three of the five arguments against path
templates, so the template stays and gains two additive fields instead
(
docs/layout/model.md, #293). The placement work is nolonger breaking at all.
Three items have since been dropped or added:
spec.mode: Observe|Write— dropped. Over a suspended target it bought only the differencebetween a pause and a declared posture. A suspended target that keeps scanning and publishing
status.placementis the same adoption dry run with one field instead of two.suspendmustkeep observing, which deviates from Flux, where
suspendstops reconciliation altogether; thatgoes in the field's docs.
GitTarget.spec.interval— dropped. Every input that changes what a scan would concludearrives as an event, on a watch. Flux polls because a Git remote cannot be watched, which is
exactly why
GitProvider.spec.intervalstays. The residual gap (a folder someone else editswhile we write nothing) is covered on demand by the reconcile-request annotation.
GitTarget.spec.allowedSourceNamespaces, so it breaks the same object B4 breaks and must ridethe same bump. It is also the only member that makes the API smaller
(
docs/design/source-scope-simplification.md).Why one wave rather than several changes
The consumer pins us three ways (image, Go module,
requireline), so each breaking release costs acoordinated bump. That argues for batching, and it is the weaker half of the argument.
The stronger half survives in reduced form: several of these items are the same design decision seen
from different angles, and building them separately means deciding it several times, inconsistently.
spec.suspendsays whether we write to the folder.commitWindowandcommit.messagesay how writes to it are batched and phrased, and today theylive on
GitProvider, which is the connection.serializeNamespaceandkustomizeRootsay what the documents in it look like — and these areadditive, so they ship without a bump.
Contents
spec.layoutserializeNamespace/kustomizeRootwork is notbreaking and does not belong to this wave ([FEATURE] A layout is the declared thing, not a path: GitTarget.spec.layout #293)
spec.mode: Observe|Writespec.suspend+ therequestedAtannotation andstatus.lastHandledReconcileAt(maintainer review F6).
spec.intervalonGitTargetGitProvider, which pollscommitWindow/commit.messagemove fromGitProvidertoGitTarget(config surface B4)allowedSourceNamespacesremoved,allowSourceNamespaceOverride→allowAnySourceNamespace,allowedNamespaces→accessFrom,sourceNamespace: "*"redefined as one cluster-wide list and watch
CommitRequestTTL / ownerRef + thedeleteverb (maintainer review F10)CommitRequest.spec.author, SAR-guarded (consumer ci(deps): Bump softprops/action-gh-release from 1 to 2 #5)status.observedDestination(consumer deps(deps): Bump github.com/onsi/gomega from 1.36.1 to 1.38.0 #6)meta.LocalObjectReferencefor the name half of our reference shapes (F12)TooManyStreamscap — sequenced after the*redefinition, which removes thefan-out it was written to bound
defaultClusterProvidererror messageVersion stays
v1alpha3: loud rejection of removed fields for one release, rather than paying for aconversion path. The
scope: Namespacedstatus-write envtest (F9) runs before any of this isplanned, because its answer constrains the enum work.