docs(advanced): add Lockfiles and build stamps page#417
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Advanced” developer-reference guide explaining Avocado’s reproducibility mechanisms (lockfiles + build stamps) and wires it into the guides sidebar so it’s discoverable alongside other advanced topics.
Changes:
- Add a new
Lockfiles and build stampsadvanced guide page covering lock/unlock workflows, stamp invalidation, and troubleshooting actions. - Insert the new page into the Developer Reference → Advanced sidebar list after “Customizing the rootfs and initramfs”.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| src/sidebars-guides.js | Adds the new advanced doc ID to the “Advanced” sidebar items list. |
| src/docs-guides/lockfiles-and-build-stamps.md | Introduces a new conceptual + troubleshooting reference for lockfiles and build-stamp caching. |
Comments suppressed due to low confidence (1)
src/docs-guides/lockfiles-and-build-stamps.md:142
- The troubleshooting row suggests
avocado clean --stamps --unlock, butavocado cleanrequires-C/--configand--targetwhenever--stampsor--unlockis used. Please update the suggested command (or add those required flags in the table) to match the CLI’s required arguments.
| Build skipping a step you expected to re-run | Inputs unchanged, stamp still valid | `avocado --no-stamps <cmd>` for a one-off, or `avocado clean --stamps` to reset |
| Build reusing an old package version after a feed update | Lockfile pinning the old version | `avocado unlock --<scope>` then `avocado install` |
| Build seems to ignore an `avocado.yaml` edit | Section hash unchanged or unrelated to the edit | Check the section you edited matches the component's stamp scope; if it should invalidate, `--no-stamps` to confirm |
| Want a fully clean re-build | Both layers stale or you want to start from scratch | `avocado clean --stamps --unlock` (clears both), then re-install / re-build |
`avocado clean --stamps --unlock` is the heaviest reset short of `avocado clean` removing the container volume entirely — it nukes both subsystems' state for the target but leaves your sources and the SDK image alone.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mobileoverlord
approved these changes
May 18, 2026
- Clarify schema v6 per-runtime extension structure alongside top-level extensions map - Add example for avocado clean --unlock showing required -C and --target flags - Replace misleading "avocado image" reference with concrete component image subcommands - Update customizing-rootfs-initramfs lockfile reference from stale avocado.lock to .avocado/lock.json and link to the new advanced page
The previous wording ("recorded after each successful install") implied
re-writing on every install, which contradicts the new Lockfiles page.
Reword to make the on-first-install + unlock-to-update semantics explicit.
nicksinas
force-pushed
the
nsinas/advanced-lockfiles-stamps
branch
from
5febe2c to
f337383
Compare
| @@ -152,4 +152,4 @@ If you remove a package from the `packages` map, the CLI detects the removal on | |||
|
|
|||
| ## Lock file | |||
| - A **lockfile** that pins package versions on first install so subsequent builds are reproducible. This is your _input_ state. | ||
| - A **stamp** cache that tracks which build steps have already succeeded so they don't re-run unnecessarily. This is your _output_ state. | ||
|
|
||
| You generally don't think about either of these — they just make builds reproducible and fast. But when something goes wrong (an apparently stale build, a package that won't update, a partial failure that "stuck"), knowing how they work is what gets you unstuck. This page covers both, plus the commands for invalidating them. |
Comment on lines
+84
to
+89
| The file layout uses one stamp per (command, component, name) tuple: | ||
|
|
||
| ``` | ||
| $AVOCADO_PREFIX/.stamps/ | ||
| ├── sdk/<host_arch>/install.stamp | ||
| ├── sdk/<host_arch>/compile-deps.stamp |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Advanced-section page documenting Avocado's two internal subsystems that govern reproducible builds:
.avocado/lock.json) — pin package versions per (target, sysroot) scope so subsequent installs reproduce byte-identical sysroots. Covers the scope flag matrix onavocado unlock(--sdk,--rootfs,--initramfs,--extension,--runtime), the broaderavocado clean --unlockequivalent, and the typical update workflow.$AVOCADO_PREFIX/.stamps/inside the SDK container) — cache successful command completions so steps don't re-run unnecessarily. Covers the file layout, what invalidates a stamp (config-section + package-list SHA-256 hashes), prerequisite chaining, partial-failure resume semantics,--no-stampsglobal flag, andavocado clean --stamps.Closes the long-standing documentation gap (sources 015, 016) — until now these systems were observable from CLI output and flag descriptions but had no conceptual reference. The page ends with a symptom → action table so it also serves as a troubleshooting entry point.
Combined into a single page (rather than two separate ones) because the subsystems answer the same user question — "why is my build doing/not doing what I expected?" — and the answer requires understanding both. Title uses the actual CLI vocabulary ("stamp", "unlock") so users grepping for terms they see in CLI output land here.
Slot: under Developer Reference / Advanced, sidebar position 9 (after
customizing-rootfs-initramfs).Test plan
/developer-reference/lockfiles-and-build-stampsand confirm the page renders.avocado unlock --help,avocado clean --help,avocado --no-stamps --help.