azldev-update-component

name

azldev-update-component

description

Read this before finalizing a component change, changing source resolution, or touching a lock file; lock edits are easy to get wrong. Explains how to refresh azldev component lock files with 'azldev comp update', covering when to run update versus render, the update/render/commit/re-render/amend workflow, and per-component versus -a refresh. Triggers include comp update, refresh lock, bump pin, change snapshot, upstream distro, lock drift, version bump, finalize 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:

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:

   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. Generated for azldev version v0.3.0.