Skip to content

Latest commit

 

History

History
80 lines (59 loc) · 7.94 KB

AGENTS.md

File metadata and controls

80 lines (59 loc) · 7.94 KB

Azure Linux — Agent Guide

For project context and architecture, see .github/copilot-instructions.md.

Mandatory Testing

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.

Examples of changes that should trigger a final test prior to sign-off (not an exhaustive list)

  • Version bumps or pinning a new upstream version
  • Adding, modifying, or removing overlays (trivial edits may only require render verification, 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)

Examples of changes that may not require testing (no effect on RPM output)

  • Moving a component definition between files (inline components.toml → dedicated <name>.comp.toml or 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.

Minimum required testing

  1. Build — azldev comp build -p <name> succeeds, RPMs appear in base/out/.
  2. Inspect — Use mock --copyin to copy the RPM into the chroot and inspect with rpm -qlp without installing. See azldev-mock.
  3. 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). See azldev-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.

Conventions

  • Always run azldev comp list -p <name> -q -O json before 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 inspect specs/<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.
  • 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 the Update Locks CI check runs against the committed state. See azldev-update-component.
  • Every commit that touches a component bumps %changelog / Release: on the next render (rpmautospec walks git log for the spec). After committing, re-render and amend so the spec tracks your commit, otherwise Check Rendered Specs will fail. See azldev-update-component for the finalize-and-amend pattern, plus the pin-bump variant.
  • Use prep-sources for deeper debugging: azldev comp prep-sources -p <name> --skip-overlays --force -o <pre-dir> -q and azldev comp prep-sources -p <name> --force -o <post-dir> -q to diff pre/post overlay output when you need to understand what upstream provides vs. what overlays change. Always use --force to overwrite an existing output dir, rm -rf requires 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 with render before doing a full build + test.
  • prep-sources -o <dir> output is ad-hoc (user-chosen dir). comp build output 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 use base/build/work/scratch/, and all temp directories should be inside it unless there's a specific reason not to be.

Do NOT use /tmp or bare mktemp -d — always use base/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".

Skills

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.

Directory Guidance