Azldev Update Component Agent Skill

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:

• Change the commit pin, upstream distro/version, or snapshot, then azldev comp update -p <name>; sanity-check locks/<name>.lock.
• 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.
• 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.
• 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>): ..."

• azldev comp render -p <name> — %changelog / Release: now reflect the new lock.
• 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.1.0.