add-config-field git:20260929.92fbe04A

Immutable. This exact content never changes and is served at /api/v1/blob/240411aede33634f.

---
name: add-config-field
description: Add, rename, or re-type a recipe or srtslurm.yaml field in srt-slurm so that it ships complete (schema, resolver, dry-run, docs, example, tests).
---

# Add or change a config field

1. **Decide where it lives.** A per-cluster or per-hardware value is a `ClusterConfig` field in `src/srtctl/core/schema.py`, read once into `RuntimeContext`. A per-recipe value goes on the owning dataclass (`SrtConfig` section, a backend protocol in `src/srtctl/backends/`, `FrontendConfig`, a service config). A value a role can override gets one resolver on the backend in the `get_config_for_mode` style; every consumer calls it.
2. **Add the field** to a frozen dataclass with a default that keeps existing recipes unchanged. Describe it in the class docstring `Attributes:` block or in a `#` comment directly above the field.
3. **Validate** at load time (`__post_init__`, the schema validators, or `FrontendProtocol.validate`) with a message that names the field and the fix, so `srtctl dry-run` catches mistakes.
4. **Wire consumers** through the resolver or protocol member, never `getattr`. A new backend answer is a new `BackendProtocol` member implemented on every backend.
5. **srun-visible fields** (env, mounts, srun options, host setup): show them in `show_config_details()` in `src/srtctl/cli/submit.py` and add a `tests/test_dry_run.py` case.
6. **Regenerate generated docs:** `uv run srtctl schema-docs`. Never edit `docs/schema-reference.md` by hand.
7. **Document** the field in the relevant `docs/` page and use it in an example under `examples/` when it is user-facing.
8. **Snapshots:** `make snapshots`. Commit any `tests/snapshots/launch/` change and make sure each diff line is intended.
9. **Check:** `make check` (Ruff, blocking `ty`, schema-doc check, all tests).