Hazmi35/turnfleet / .agents/skills/api-change
api-change
UnverifiedChange 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.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |