AGENT SKILL
api-change
Change the TURNPool API types safely - edit types and markers, regenerate, update webhooks, tests and docs. Use whenever a field is added, removed or re-marked in api/v1alpha1.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- api-change
- description
- Change the TURNPool API types safely - edit types and markers, regenerate, update webhooks, tests and docs. Use whenever a field is added, removed or re-marked in api/v1alpha1.
03 SKILL.md 正文
Changing the TURNPool API
Work in this order. Each step catches a different class of mistake.
- Edit
api/v1alpha1/turnpool_types.go.- Every field is explicitly
+optionalor+required. No floats. Ratios areportsInUse/portsTotalintegers that consumers divide. - Lists get
+listType=map++listMapKey=<key>(or+listType=atomicwith a one-line reason). Avoid maps. - Status fields are
+optionaland derived from the spec, never cached from it. Conditions stay the first status field, set withmeta.SetStatusCondition. - New enum values: extend the Go type, the
+kubebuilder:validation:Enummarker, and everyswitchover it (theexhaustivelinter fails the build otherwise). Add the doc comment on the new value, and theAGENTS.mdglossary line for it when the value names a domain concept, in the same edit.
- Every field is explicitly
- Decide mutability. Anything that would invalidate live allocations is
immutable: relay port range, addressing mode and its per-node split, realm.
Adding it to the immutability check in
internal/webhook/v1alpha1/turnpool_webhook.gois part of the change, with the reason in the validation message. - Regenerate (
make generate manifests api-docs). Never hand-editzz_generated.deepcopy.go,config/crd/bases/*,config/rbac/role.yamlordocs/api.md. - Update the webhooks: defaulting for anything with a sensible default, validating for the rules the CRD schema cannot express (mode-specific config, listener port uniqueness, ports outside the relay range, overlap between relays sharing an address).
- Update tests:
internal/webhook/v1alpha1/turnpool_webhook_test.gofor defaulting and each rejection (envtest, table-driven).internal/relaygolden files if the rendered coturn config changes; a new field that reaches the data plane always changes the goldens.test/e2e/if the field is observable from outside.
- Update docs:
docs/api.mdis generated.docs/architecture.mdanddocs/capacity-model.mdare not. A new addressing mode also needs an ADR (add-addressing-mode). - Prove it:
make ci. If the change touches the data plane,make test-e2e.
Report which files changed and which command proved the change.