Skip to content

control-plane: resolve #69 review threads (api-versioning + components) - #20

Merged
croadfeldt merged 1 commit into
mainfrom
docs/control-plane-69
Jun 28, 2026
Merged

croadfeldt merged 1 commit into
mainfrom
docs/control-plane-69

Conversation

@croadfeldt

Copy link
Copy Markdown
Owner

Resolves the open review threads on the downstream dcm #69 PR (control plane). Authored on the post-rename base, so it already uses "Gating Policy". +29/−4 across two docs.

api-versioning.md

  • "well-known fact" — defer the SemVer baseline (cite semver.org); §1.3 keeps only DCM's specific application, and §2 reframes the breaking-change list as DCM's explicit authoritative checklist (calling out the DCM-specific entries: idempotency, response envelope, auth-method removal, enum tolerance).
  • dev deprecation timeline — dev now gets no deprecation guarantee (was P60D/P90D); dev is for iteration, versions can break without a window.
  • OIS version event vs REST — §7.2 explains a version/capability change is one-to-many fan-out (event), while dispatch is point-to-point needing a result (sync REST).

components.md

  • event policy vs sync REST providers — §2.4 documents the rule: fan-out / "who cares this happened?" → events; point-to-point / "I need this result to continue" → REST.
  • match-condition syntax + always — §2.5 adds the match-condition grammar: expression syntax, the always reserved keyword (+ other reserved tokens), variable-path-by-reference vs literal, and unresolved-path = false.
  • "document every attribute" — §3.4 adds a field reference for the cost estimation/attribution objects.

Note: the DCM-side GateKeeper → Gating Policy rename landed separately in #19 (merged). Upstream source of truth; syncs to downstream #69 once merged.

api-versioning.md:
- defer the well-known SemVer baseline (cite semver.org); keep only the
  DCM-specific application
- frame the breaking-change list as DCM's explicit authoritative checklist,
  not a generic tutorial; call out the DCM-specific entries
- dev profile gets no deprecation guarantee (was P60D/P90D) — dev is for
  iteration, versions can break without a window
- §7.2: add the event-vs-REST rationale for OIS version propagation
  (version/capability change = one-to-many fan-out = event; dispatch =
  point-to-point = sync REST)

components.md:
- §2.4: document why policy evaluation is event-driven (fan-out to many
  policies) but provider dispatch is synchronous REST (point-to-point,
  result needed to advance)
- §2.5: add the match-condition grammar — expression syntax, the `always`
  reserved keyword, variable-path-by-reference vs literal, unresolved-path
  semantics
- §3.4: add a field reference for the cost estimation/attribution objects

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@croadfeldt
croadfeldt merged commit 4b055de into main Jun 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant