From 2a0570d493a6f794b5d7ff302592b8dd9711c1bb Mon Sep 17 00:00:00 2001 From: Tobias Brick Date: Fri, 30 Oct 2026 23:02:29 +0000 Subject: [PATCH] docs: encourage resilient overlays Guide agents to minimize coupling to unrelated source details while retaining enough context to target changes unambiguously. This avoids brittle overlays without prescribing a particular matching technique. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9b90d48d143..cbe502c4b99 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -103,3 +103,4 @@ Run all commands from the repo root (where `azldev.toml` lives). If the terminal 4. **Don't edit generated output**: Build artifacts in `base/out/` and `base/build/` are generated (configured by `output-dir`, `log-dir`, `work-dir` in `base/project.toml`) — never edit them directly. Note: `prep-sources -o ` writes to a user-specified directory, separate from these project output dirs. 5. **Mandatory testing**: Any change that affects a component's output (overlays, build config, spec edits, version bumps, new components) MUST be validated by building AND testing the resulting RPMs. A successful build alone is not sufficient — smoke-test in a mock chroot. Pure organizational changes (moving definitions between files, editing descriptions/comments) do not require rebuild. See `AGENTS.md` for the full testing protocol. 6. **New specs use autorelease**: For any spec we author ourselves (local specs), use `%autorelease` and `%autochangelog` rather than a static `Release:` with a hand-written `%changelog`. The default `release.calculation = "auto"` detects ordinary, unconditional `%autorelease` usage, so do not set it explicitly. Use `release = { calculation = "autorelease" }` only when auto-detection cannot identify the spec's autorelease behavior, such as when `%autorelease` is conditional. +7. **Keep overlays resilient to upstream changes**: Express the intended change with minimal dependence on unrelated source details. Avoid unnecessarily matching or reproducing surrounding formatting or content. Use enough context to target the change unambiguously, but no more than needed.