azldev-add-component

# Add a component ## Before you start Confirm the component does not already exist: ```sh azldev comp list -p <name> -q -O json ``` ### Inspect the upstream spec first The reliable way to see what you are importing (direct web fetches of upstream dist-git often fail bot detection): 1. Add a bare entry so azldev can resolve the component: run `azldev comp add <name>` (it appends `[components.<name>]` to the root config file), or hand-add `[components.<name>]` to an included config file if you want it to live elsewhere. A bare root entry is *perfect* for initial testing, but real distros will usually segment the configuration into included files. Once the initial pass is done, ensure the component is in the right place and remove the root entry. 2. Create the initial lock so source resolution is pinned before inspection: ```sh azldev comp update -p <name> ``` 3. Pull the sources without overlays into a scratch dir under the work dir: ```sh azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name> -q ``` 4. Read the spec and plan any overlays. ## Inline vs dedicated file - **Inline** — a bare upstream import with no changes stays in a shared config file: ```toml [components.jq] ``` - **Dedicated** — anything that needs overlays, build config, or a local spec gets its own `<name>/<name>.comp.toml`. Rule of thumb: more than `[components.<name>]` earns a dedicated file. An `includes = ["**/*.comp.toml"]` glob picks it up automatically. `azldev comp add <name> [<name>...]` adds bare `[components.<name>]` entries that inherit the distro defaults; it writes to the **root** config file and does not scaffold spec or source files. If your distro keeps components in included or dedicated files, move the entry there afterward. ## Customize For spec source types and overlays, read the `azldev-comp-toml` and `azldev-overlays` skills. Key points when adding a component: - Prefer **overlays** over forking the spec — overlays get upstream updates for free. Forking a spec is a last resort and a long-term maintenance commitment. Get explicit user sign-off first, document every change, and keep the delta minimal. - Every overlay needs a `description` explaining why it is needed. - Keep `%check` enabled. Disable it only as a last resort via `build.check.skip = true` with a required `build.check.skip_reason` (see the `azldev-build-component` skill). ## Validate The initial lock pins the upstream revision you inspected. Refresh it after the component inputs settle, then validate: ```sh azldev comp update -p <name> # resolve the upstream commit and write the lock azldev comp render -p <name> # apply overlays and write the rendered spec azldev comp diff-sources -p <name> # see exactly what the overlays change azldev comp build -p <name> # build the RPMs ``` Inspect the rendered spec under `specs/`. A new component always needs a smoke test — see the `azldev-build-component` and `azldev-mock` skills. After all component inputs are final, run `azldev comp update -p <name>` again and re-render. Stage the component definition and sources, `locks/<name>.lock`, and the rendered output before committing. Then re-render, stage `specs/<first-char>/<name>/`, and amend the commit so `%changelog` and `Release:` reflect it. See the `azldev-update-component` skill for the complete finalization workflow. Generated by `azldev docs agent`; do not hand-edit.