docs: fill the avocado.yaml configuration gaps - #516
Open
lee-reinhardt wants to merge 1 commit into
Open
lee-reinhardt wants to merge 1 commit into
lee-reinhardt wants to merge 1 commit into
Conversation
The configuration guide gave rootfs and initramfs a three-field table, had no permissions section, and explained the one-entry versus named-entries forms only for kernel, which is where users get lost. Adds a section on how the CLI tells the two forms apart and the typo that silently turns a field into an entry name; documents every rootfs and initramfs field, including post_install replacing the built-in steps and which fields a per-target block carries; and adds a permissions section with every user and group field and its quirks. The overlay section described merge as rsync and opaque as replacing directory contents. Merge is cp -a, opaque is cp -r, and neither removes anything, so that is corrected. A short section covers the CLI's warnings for ignored keys and the schema comment for editor support.
Contributor
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
Only minor documentation clarifications remain; no blocking issues were identified.
Review effort: Lite
Findings: None
What changed in this PR
Expands the Avocado CLI configuration guide with documentation for rootfs, initramfs, overlays, permissions, and validation.
Changes:
- Clarifies configuration entry forms and field behavior.
- Documents rootfs, initramfs, overlay, and permissions options.
- Adds configuration warnings and YAML schema editor guidance.
| File | Description |
|---|---|
src/docs-guides/avocado-cli/configuration.md |
Expands Avocado configuration documentation. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This branch has not been deployed
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.
Important
Don't merge until avocado-linux/avocado-cli#286 ships in a CLI release. The "Checking your config" section documents warnings that only exist once that release is out. Merging after the release also triggers the docs deploy that picks up the released schema (#515).
Problem
A user evaluating Avocado couldn't find how
rootfs,initramfsandpermissionswork: the configuration guide gave rootfs and initramfs a three-field table, had no permissions section at all, and explained the one-entry versus named-entries forms only forkernel. The overlay section was also wrong about what the two modes do.Change
All in
docs-guides/avocado-cli/configuration.md:rootfs,initramfs,kernelandpermissions, and the misspelling that silently turns a field into an entry name (permissions: { user: ... }). Notes that for images only thedefaultentry is built and some fields are read only in the one-configuration form.permissions,post_install(which replaces the built-in post-install steps),imageandsource, and that atarget-<name>:block only carriespost_installandimage.cp -a(not rsync), opaque copies withcp -r, and neither removes files already in the sysroot. The old text said opaque "fully replaces directory contents".dirdefaults tooverlayrather than being required, andpreprocessis documented.groupsentry is skipped, an omittedgidtakes the UID value, and a user'sdisabledand a group'spasswordhave no effect.yaml-language-serverschema comment for editor support.Every statement was checked against avocado-cli's source at
d5d7049.Merge order
The "Checking your config" section describes behaviour from avocado-linux/avocado-cli#286, and the editor-support line assumes the site serves the new schema (#515). The rest is accurate for today's CLI. Merge with or after the CLI release that ships #286, or drop that section until then.
Testing
prettier --check ., lint, the full build (which fails on broken links and anchors) andcheck-mermaidpass.