Skip to content

Hazmi35/turnfleet / .agents/skills/api-change

api-change

Verified

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.

FileKindSize
SKILL.mdskill md2.5 KB
---
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.
---

# Changing the TURNPool API

Work in this order. Each step catches a different class of mistake.

1. **Edit `api/v1alpha1/turnpool_types.go`.**
   - Every field is explicitly `+optional` or `+required`. No floats. Ratios are
     `portsInUse`/`portsTotal` integers that consumers divide.
   - Lists get `+listType=map` + `+listMapKey=<key>` (or `+listType=atomic` with
     a one-line reason). Avoid maps.
   - Status fields are `+optional` and derived from the spec, never cached
     from it. Conditions stay the first status field, set with
     `meta.SetStatusCondition`.
   - New enum values: extend the Go type, the `+kubebuilder:validation:Enum`
     marker, and every `switch` over it (the `exhaustive` linter fails the
     build otherwise). Add the doc comment on the new value, and the
     `AGENTS.md` glossary line for it when the value names a domain concept, in
     the same edit.
2. **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.go` is part of the change, with
   the reason in the validation message.
3. **Regenerate** (`make generate manifests api-docs`). Never hand-edit
   `zz_generated.deepcopy.go`, `config/crd/bases/*`, `config/rbac/role.yaml` or
   `docs/api.md`.
4. **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).
5. **Update tests**:
   - `internal/webhook/v1alpha1/turnpool_webhook_test.go` for defaulting and
     each rejection (envtest, table-driven).
   - `internal/relay` golden 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.
6. **Update docs**: `docs/api.md` is generated. `docs/architecture.md` and
   `docs/capacity-model.md` are not. A new addressing mode also needs an ADR
   (`add-addressing-mode`).
7. **Prove it**: `make ci`. If the change touches the data plane,
   `make test-e2e`.

Report which files changed and which command proved the change.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall