For project context and architecture, see .github/copilot-instructions.md.
USE YOUR BEST JUDGEMENT, but when in doubt, test. If your change could affect the built RPMs, smoke-test before reporting success. See
azldev-mock.
- Version bumps or pinning a new upstream version
- Adding, modifying, or removing overlays (trivial edits may only require
renderverification, but when in doubt, do a full build + smoke-test) - Changing build config (
build.defines,build.with,build.without) - Modifying local spec files or source files (again, trivial edits may not require a full rebuild, but when in doubt, test)
- Adding a new component (first build)
- Moving a component definition between files (inline
components.toml→ dedicated<name>.comp.tomlor vice versa) - Editing only component metadata fields (e.g., overlay descriptions, build descriptions, comments) without changing actual build config or overlays
- Adding or editing TOML comments
- Pure documentation or formatting changes
Isolated latest-only local builds: Validate local component builds in a clean, task-specific mock root, exposing only the newest available RPM version per package name and architecture across all enabled repositories, including local repositories. Historical RPMs and previously installed dependencies must not mask missing or incompatible prerequisites. best=1 alone does not enforce this policy. For dependency chains, expose only prerequisites already validated earlier in the chain.
- Build —
azldev comp build -p <name>succeeds, RPMs appear inbase/out/. - Inspect — Use
mock --copyinto copy the RPM into the chroot and inspect withrpm -qlpwithout installing. Seeazldev-mock. - Smoke-test — Use a mock chroot (
azldev adv mock shell --add-package /path/to/rpm) to install and validate basic functionality (e.g.,<binary> --version, service starts, library loads). Seeazldev-mock.
Do NOT skip testing for changes that affect RPM output. Do NOT tell the user "the build succeeded" without also running the smoke-test. If testing cannot be performed (e.g., the package has no runnable binary, or some other issue), explicitly document why and what was verified instead.
- Always run
azldev comp list -p <name> -q -O jsonbefore modifying a component. - Prefer overlays over forking/local specs when customizing upstream packages.
- After modifying overlays or component config, re-render with
azldev comp render -p <name>and inspectspecs/<first-char>/<name>/to verify the result. This is the fastest verification path.- Note: Changing a global snapshot time may affect all components that depend on it, potentially causing widespread rebuilds. Full re-render is time-consuming, but may be done by
azldev comp render -a --clean-stale.
- Note: Changing a global snapshot time may affect all components that depend on it, potentially causing widespread rebuilds. Full re-render is time-consuming, but may be done by
- Always re-run
azldev comp update -p <name>before opening a PR, even for minor edits — lock fingerprints are computed from the full component config, and theUpdate LocksCI check runs against the committed state. Seeazldev-update-component. - Every commit that touches a component bumps
%changelog/Release:on the next render (rpmautospec walksgit logfor the spec). After committing, re-render and amend so the spec tracks your commit, otherwiseCheck Rendered Specswill fail. Seeazldev-update-componentfor the finalize-and-amend pattern, plus the pin-bump variant. - Use
prep-sourcesfor deeper debugging:azldev comp prep-sources -p <name> --skip-overlays --force -o <pre-dir> -qandazldev comp prep-sources -p <name> --force -o <post-dir> -qto diff pre/post overlay output when you need to understand what upstream provides vs. what overlays change. Always use--forceto overwrite an existing output dir,rm -rfrequires user confirmation which is disruptive. - Follow the inner loop cycle: investigate → modify → render → build → test → inspect. See
azldev-build-component.- Note: Use your best judgement, some packages are VERY slow to build (e.g.,
kernel), in those cases you may want to do multiple iterations of investigate → modify → verify withrenderbefore doing a full build + test.
- Note: Use your best judgement, some packages are VERY slow to build (e.g.,
prep-sources -o <dir>output is ad-hoc (user-chosen dir).comp buildoutput goes to project-configured dirs (base/out/,base/build/). Don't conflate them.- For temporary files, ensure they are all placed inside the project's defined work directory (
azldev config dump -q -f json 2>&1 | grep 'workDir'). Example commands usebase/build/work/scratch/, and all temp directories should be inside it unless there's a specific reason not to be.
Do NOT use
/tmpor baremktemp -d— always usebase/build/work/scratch/(or a subdirectory) for temporary files. This avoids permission issues and keeps all working files inside the project tree.
Example: workDir="/home/user/azurelinux/base/build/work", use "./base/build/work/scratch/" for all temp dirs, or a subdir like "./base/build/work/scratch/thing".
Detailed workflows live in skills (loaded on-demand when relevant):
| Task | Skill |
|---|---|
| Use azldev or edit distro configuration | azldev |
| Build a component, debug build failures | azldev-build-component |
| Bump a component's upstream pin (lock files) | azldev-update-component |
| Add a new component to the distro | azldev-add-component |
| Remove component(s) from the distro | azldev-remove-component |
| Diagnose and fix overlay issues | azldev-overlays |
| Test and inspect packages in mock chroot | azldev-mock |
| Review component for hygiene and best practices | azldev-comp-toml review checklist |
| Build, boot, test, or configure images | azldev-image |
| Triage Koji build failures | skill-koji-triage |
| Batch-triage build failures from results file | skill-mass-triage |
| Fix Stage 1 Fedora mirror dependency gaps (injections) | skill-fedora-mirror-injections |
| Inspect Koji AKS cluster health and node pools | skill-aks-health |
| Resolve Koji AKS deployment context | skill-deployment-context |
| KQL queries for Koji logs, pods, and events | skill-kql-queries |
| Query Azure Monitor metrics for Koji AKS | skill-metrics |
Azure infra workflow ordering: Before running any KQL log queries, metrics queries, or AKS health checks, always resolve deployment context first using
skill-deployment-context. This provides the resource group, cluster name, subscription, and Log Analytics workspace needed by the other Azure skills.
- Components:
base/comps/AGENTS.md— file organization rules - Distro config:
distro/AGENTS.md— build defaults, shared config