avocado: update extensions reference

[mobileoverlord]

Update extensions reference to more comprehensively document extension sources and functionality

[Copilot]

Pull request overview

This PR comprehensively updates the Avocado Linux extensions reference documentation. The previous brief overview has been replaced with detailed, structured documentation that covers extension types, configuration patterns, SDK integration, runtime behavior, and organizational best practices.

Changes:

• Expanded documentation from 28 lines to over 630 lines with comprehensive coverage of the extension system
• Added detailed sections on extension definition, external sources, SDK integration, runtime behavior, and organizational patterns
• Included practical YAML examples demonstrating common extension configurations and use cases

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The example shows an empty password string which could be a security concern. Consider adding a note explaining that empty passwords should be avoided in production or clarifying the security implications of this configuration pattern.

Suggested change

	password: ''
	# Never use empty passwords in production. Replace with a strong, secure password.
	password: 'CHANGEME_SECURE_PASSWORD'

[Copilot]

The command example uses --no-block flag with systemctl restart. Consider adding documentation about why this flag is important for merge hooks (to prevent blocking the merge process) to help users understand when to use it.

[Copilot]

The section describes "Certain hooks are added automatically" but uses passive voice that could be clearer. The documentation would benefit from explicitly stating which component adds these hooks (e.g., "The Avocado build system automatically adds hooks for..." or "avocadoctl automatically runs...") to clarify when this automation occurs.

[Copilot]

Missing validation guidance for the AVOCADO_ON_MERGE field. Since this field executes arbitrary commands during merge, the documentation should warn users about security implications and recommend validation practices for commands specified in this field.

Suggested change

The `AVOCADO_ON_MERGE` field specifies commands to run after merging (e.g., `depmod` for kernel modules, `ldconfig` for shared libraries).

The `AVOCADO_ON_MERGE` field specifies commands to run after merging (e.g., `depmod` for kernel modules, `ldconfig` for shared libraries). Because these commands may be executed with elevated privileges as part of the merge process, this field is security-sensitive and must not be populated from untrusted or user-supplied input. In production, restrict the allowed commands and arguments for `AVOCADO_ON_MERGE` (for example via policy, schema validation, or CI checks), prefer invoking reviewed scripts checked into version control over ad‑hoc shell fragments, and require code review for any changes to this field in extension definitions.

[Copilot]

The sparse_checkout configuration uses singular "sparse_checkout" but lists multiple paths in an array. Consider clarifying whether the property name should be singular or plural, or add a note about the naming convention to prevent confusion.

Suggested change

	sparse_checkout:
	sparse_checkout:
	# Note: sparse_checkout is intentionally singular but accepts multiple paths.

[Copilot]

The table formatting uses inconsistent spacing. The Description column entries have varying amounts of detail, and some entries could be more descriptive. For example, "Build-time SDK package dependencies" could specify what kinds of packages or provide an example.

Suggested change

	| Pattern | Description |
	| ------------------------------- | ------------------------------------------------------- |
	| `provision_profiles.*` | Vendor provisioning profiles (tegraflash, sd-card, USB) |
	| `provision_profiles.tegraflash` | Specific provisioning profile |
	| `sdk.packages.*` | Build-time SDK package dependencies |
	| `sdk.compile.*` | Cross-compilation sections |
	| Pattern | Description |
	| ------------------------------- | --------------------------------------------------------------------------- |
	| `provision_profiles.*` | Vendor provisioning profiles (tegraflash, sd-card, USB) |
	| `provision_profiles.tegraflash` | Specific provisioning profile |
	| `sdk.packages.*` | Build-time SDK package groups (for example compilers, debuggers, headers) |
	| `sdk.compile.*` | Cross-compilation configuration sections (architectures, flags, sysroots) |

[Copilot]

The documentation states extensions "cannot modify the immutable base system" but earlier sections describe mutable modes that allow writes. This creates potential confusion. Consider clarifying that while extensions can provide writable overlays in certain modes, the underlying base system image remains immutable.

Suggested change

	Multiple extensions compose together with clear isolation boundaries. Each extension contains complete dependencies and cannot modify the immutable base system. The base system provides the trusted foundation while extensions deliver functionality.
	Multiple extensions compose together with clear isolation boundaries: each extension contains complete dependencies and cannot directly modify the immutable base system image. Even in mutable modes, any writes occur in extension-specific writable overlays or data partitions, while the base OS image remains unchanged and provides the trusted foundation that extensions build upon.

[Copilot]

The statement "The users and groups properties are intended for real user accounts that require login credentials, home directories, and shell access" could be misleading. Configuration should not handle login credentials directly, and passwords should typically be managed separately. Consider clarifying that these properties configure user account metadata, not actual credentials.

Suggested change

	Configuration extensions can manage user accounts and groups. The `users` and `groups` properties are intended for real user accounts that require login credentials, home directories, and shell access:
	Configuration extensions can manage user accounts and groups. The `users` and `groups` properties configure user and group metadata (such as home directories, shells, and group memberships) for system accounts; they are not intended for storing actual login credentials, which should be managed separately via your system's authentication tooling or a secrets manager: