azldev-update-component

# Update component lock files `azldev comp update` (`comp` is an alias for `component`) refreshes one or more component lock files under `locks/`. A lock pins the resolved upstream commit plus an input fingerprint computed from the component's render inputs — its TOML config, overlays, the pinned upstream commit, and the distro release version. If any of those change, the lock is stale. ## When to run `update` | Situation | Run `update`? | | --- | --- | | Adding a new upstream component (no lock yet) | **Yes** — first, to create the lock before `render`/`build` can resolve it | | Finalizing a component change for a PR | **Yes** — once at the end | | Changing source resolution (commit pin, upstream distro/version, or snapshot) | **Yes** — also mid-workflow (see below) | | Iterating on overlays / build config / metadata | No — once the lock exists, `render` alone is enough while iterating | | Just reading or building existing components | No | Refresh a single component with `-p <name>`. Use `-a` (all components) only for coordinated mass refreshes (e.g. a new distro snapshot) or when investigating lock drift across many components — it is slow. For day-to-day work use `-p`. Add `-O json` for machine-readable lock output when debugging. ## End-of-work refresh (the common case) For most edits — overlays, build flags, metadata — run `update` once at the end, then re-render *after committing* so the generated changelog and release reflect your new commit: ```sh azldev comp update -p <name> azldev comp render -p <name> git add <changed-component-config-and-source-paths> \ locks/<name>.lock \ specs/<first-char>/<name>/ git commit -m "fix(<name>): ..." # Re-render and amend so the changelog / Release: track the new commit. azldev comp render -p <name> git add specs/<first-char>/<name>/ git commit --amend --no-edit ``` ### Why the second render-and-amend? Changelog generation and release calculation are separate. When a spec uses `%autochangelog`, rpmautospec derives it from the component's **git history** for every release mode. For non-manual release modes, azldev also derives or bumps `Release:` from that history. The first render happens before your commit exists, so a fresh render *after* committing incorporates the new changelog entry and any automatic release bump. Amending folds that output into a single clean commit and keeps rendered-spec / lock CI gates (which run against committed state) green. For a component with `release.calculation = "manual"`, increment the release counter yourself in the same change. Manual mode is not an exemption from the post-commit render-stage-amend cycle: when the spec uses `%autochangelog`, that render incorporates the new commit. ## Changing source resolution A source-resolution change follows the same rule, using one commit followed by a post-render amend: 1. Change the commit pin, upstream distro/version, or snapshot, then `azldev comp update -p <name>`; sanity-check `locks/<name>.lock`. 2. `azldev comp render -p <name>` — the spec body now tracks the newly resolved source. `%changelog` / `Release:` still reflect the previous source; that is expected until you commit. 3. Iterate on overlays / patches / build config as the new source requires, re-rendering after each change. Re-run `update` only if you change a source-resolution input again. 4. `azldev comp update -p <name>`, then stage and commit all component inputs changed above with the refreshed lock and rendered output: ```sh git add <changed-component-config-and-source-paths> \ locks/<name>.lock \ specs/<first-char>/<name>/ git commit -m "update(<name>): ..." ``` 5. `azldev comp render -p <name>` — `%changelog` / `Release:` now reflect the new lock. 6. `git add specs/<first-char>/<name>/`, then `git commit --amend --no-edit` so the source change and rendered output land together. Generated by `azldev docs agent`; do not hand-edit.