Add developer guide for the desktop submodule#912
Merged
igorpecovnik merged 13 commits intomainfrom Apr 20, 2026
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds docs/Developer-Guide_Desktops.md, a comprehensive developer reference for the Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
size/large
3 tasks
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/Developer-Guide_Desktops.md`:
- Around line 730-732: The fenced code block containing the line "#
AutomaticLoginEnable = true" lacks a language tag (MD040); update that fence to
include an explicit language such as ini (e.g., change the opening backticks
from ``` to ```ini) so the block renders and lints correctly and consistently.
- Around line 111-113: The fragment links to `#tier-blocks` and `#tier-overrides`
are broken because the generated heading IDs differ; update the Markdown
headings "Tier blocks (tiers.<tier>)" and "tier_overrides" to include explicit
HTML ID anchors matching the link targets (e.g., change the heading lines to
include {`#tier-blocks`} and {`#tier-overrides`} respectively) so the links from the
table resolve correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 2705f568-aca3-4400-937c-c316c58480af
📒 Files selected for processing (2)
docs/Developer-Guide_Desktops.mdmkdocs.yml
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/Developer-Guide_Desktops.md (2)
112-112:⚠️ Potential issue | 🟡 MinorFix broken anchor target for
tier_overrideslink.Line 112 links to
#tier-overrides, but the heading slug from### tier_overridesresolves to#tier_overrides. Update either the link target or add an explicit heading ID so TOC/internal navigation works reliably.Proposed fix
-| `tier_overrides` | mapping | optional | Per-arch and/or per-release-per-arch package removals (and additions) for tier holes. See [tier_overrides](`#tier-overrides`). | +| `tier_overrides` | mapping | optional | Per-arch and/or per-release-per-arch package removals (and additions) for tier holes. See [tier_overrides](`#tier_overrides`). |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/Developer-Guide_Desktops.md` at line 112, Update the broken anchor for the `tier_overrides` link: locate the link text "`tier_overrides`" that currently points to `#tier-overrides` and either change the href to `#tier_overrides` or add an explicit id to the heading `### tier_overrides` (for example `### tier_overrides {`#tier-overrides`}`) so the internal TOC/navigation resolves correctly; ensure the link target and the heading id/slug match exactly.
766-768:⚠️ Potential issue | 🟡 MinorAdd a language tag to this fenced block.
This fence is unlabeled; use
ini(ortext) for consistent markdown linting/rendering.Proposed fix
-``` +```ini # AutomaticLoginEnable = true🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/Developer-Guide_Desktops.md` around lines 766 - 768, The fenced code block containing "# AutomaticLoginEnable = true" is unlabeled; update the markdown by adding a language tag (use `ini` or `text`) to the opening fence so it reads triple-backticks with `ini` (e.g., change "```" to "```ini") to satisfy markdown linting and ensure consistent rendering for the block referenced by the comment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/Developer-Guide_Desktops.md`:
- Line 112: Update the broken anchor for the `tier_overrides` link: locate the
link text "`tier_overrides`" that currently points to `#tier-overrides` and
either change the href to `#tier_overrides` or add an explicit id to the heading
`### tier_overrides` (for example `### tier_overrides {`#tier-overrides`}`) so the
internal TOC/navigation resolves correctly; ensure the link target and the
heading id/slug match exactly.
- Around line 766-768: The fenced code block containing "# AutomaticLoginEnable
= true" is unlabeled; update the markdown by adding a language tag (use `ini` or
`text`) to the opening fence so it reads triple-backticks with `ini` (e.g.,
change "```" to "```ini") to satisfy markdown linting and ensure consistent
rendering for the block referenced by the comment.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 13ae8264-09e4-482a-b5d7-32a2c32642f2
📒 Files selected for processing (1)
docs/Developer-Guide_Desktops.md
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/Developer-Guide_Desktops.md (2)
766-768:⚠️ Potential issue | 🟡 MinorAdd a language tag to the fenced config snippet.
The code block starting at Line 766 should declare a language (
inifits here) for lint/render consistency.Proposed fix
-``` +```ini # AutomaticLoginEnable = true</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/Developer-Guide_Desktops.mdaround lines 766 - 768, Update the fenced
code block containing the line "# AutomaticLoginEnable = true" to include the
language tag "ini" by changing the opening triple backticks to ```ini so the
snippet is rendered/linted as INI; locate the block with that exact comment
marker and replace the fence accordingly.</details> --- `112-112`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the `tier_overrides` fragment target mismatch.** Line 112 links to `#tier-overrides`, but the heading at Line 137 is `tier_overrides`, which can resolve to a different fragment ID in Markdown renderers. Align them explicitly. <details> <summary>Proposed fix</summary> ```diff -| `tier_overrides` | mapping | optional | Per-arch and/or per-release-per-arch package removals (and additions) for tier holes. See [tier_overrides](`#tier-overrides`). | +| `tier_overrides` | mapping | optional | Per-arch and/or per-release-per-arch package removals (and additions) for tier holes. See [tier_overrides](`#tier_overrides`). | ``` </details> Also applies to: 137-137 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/Developer-Guide_Desktops.md` at line 112, The fragment target mismatch: the table links to `#tier-overrides` but the actual heading is `tier_overrides`, so update either the link or the heading so they match exactly; specifically change the table link `#tier-overrides` to `#tier_overrides` (or rename the heading `tier_overrides` to `tier-overrides`) so the fragment ID for the `tier_overrides` section and the anchor used in the table are identical and will resolve correctly in Markdown renderers. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@docs/Developer-Guide_Desktops.md:
- Around line 766-768: Update the fenced code block containing the line "#
AutomaticLoginEnable = true" to include the language tag "ini" by changing the
opening triple backticks to ```ini so the snippet is rendered/linted as INI;
locate the block with that exact comment marker and replace the fence
accordingly.- Line 112: The fragment target mismatch: the table links to
#tier-overrides
but the actual heading istier_overrides, so update either the link or the
heading so they match exactly; specifically change the table link
#tier-overridesto#tier_overrides(or rename the headingtier_overrides
totier-overrides) so the fragment ID for thetier_overridessection and the
anchor used in the table are identical and will resolve correctly in Markdown
renderers.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `067835e9-8fc0-4985-8143-c3cc851580e9` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 1567932e762df43e9aeac6e8e291053299f6ad01 and 39e956f0bb5c2ccf74f7e906d1dbd1d9d61e90c2. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `docs/Developer-Guide_Desktops.md` * `docs/css/armbian-extra.css` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * docs/css/armbian-extra.css </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Technical reference for tools/modules/desktops/ in configng: component map, YAML schema, parse_desktop_yaml.py CLI surface, all bash module functions, install/remove lifecycle, container/CI behavior, "adding a new desktop" walkthrough, and security notes (path traversal guard, shell-escape, GPG keyring fetch). Filed under ARMBIAN BUILD FRAMEWORK alongside Extensions, since it documents an internal API rather than end-user steps.
The guide was written before the tier system landed in configng. Update it to match the current state of the desktop submodule on smallfixes. Highlights of what changed in the doc: - Add an Overview section explaining the three-tier model (minimal/mid/full), the tier_overrides escape hatch, and the per-install manifest files. - Replace the YAML schema section. The flat top-level `packages:` / `packages_uninstall:` is gone — every DE uses a `tiers:` map keyed by minimal/mid/full now. packages_uninstall belongs under tiers.minimal. Add documentation for `tier_overrides` (per-arch and per-release-per-arch layers) and the `browser:` virtual token map (per-release-per-arch with explanation of why Debian needs firefox-esr and Ubuntu needs epiphany-browser). - Add example KDE Plasma YAML showing how per-DE tier overrides drop common entries (gnome-text-editor, file-roller, loupe) and substitute KDE equivalents (kate). - Document the full common.yaml shape with tiers + browser map + tier_overrides for every release/arch hole the audit found (loupe missing on bookworm, thunderbird missing on noble/plucky as snap-shim, etc.). - Rewrite the parser CLI section. --tier is now mandatory. Document the resolution algorithm step-by-step. - Rewrite the bash module API table. New commands: upgrade, downgrade, set-tier, tier, at-tier. Existing commands changed: install requires tier=, status is now silent on both paths, auto/manual edit gdm config in place, login uses an anchored regex. - Document the manifest files (.packages and .tier under /etc/armbian/desktop/) and what they're used for. - Document the gdm3 daemon.conf-vs-custom.conf branching by ID= (not by codename), the in-place edit behavior, and the anchored login regex. - Add Lifecycle sections for install, remove, and upgrade/downgrade. The install lifecycle now shows fail-safe behavior: pkg_install failures bail before flipping default.target. The remove lifecycle shows the multi-user.target switch and isolate that drops the running session to console without a reboot. - Add a "Common pitfalls" section documenting the three cascade traps we hit during the smallfixes work: packages_uninstall yanking metapackages, daemon.conf vs custom.conf wrong-file branching, and the unanchored login regex matching the noble template's commented sample line. - Update the "Adding a new desktop" walkthrough to test every tier and to show the JSON menu ID slot allocation (01/02/03/04 existing actions, 05/06 mid/full installs, 07/08/09 change-tier entries). The guide is now ~750 lines, up from ~395, reflecting the ~10x growth of the desktop submodule's surface area in this release.
The auto-generated left-nav was rendering badly:
- YAML schema sub-headers like
'Per-release block (releases.<codename>)' had angle
brackets that mkdocs's TOC generator passed through
as raw text, producing 'releases <codename>' with
a literal '<' / '>' character and a missing dot.
- Bash module API headers carried the full function
signature inline, e.g.
module_desktops <command> [de=<name>] [tier=<tier>]
[arch=<arch>] [release=<release>]
This wrapped over multiple lines in the sidebar and
looked like garbage.
Two fixes:
1. Drop angle-bracket parameter hints from every header.
The schema sections become 'Tier blocks',
'Per-release block', 'Custom repository block', etc.
The information that used to be in the header (the
parent path like releases.<codename>) is already
covered in the body text.
2. For each bash module function, the header is now just
the function name (no signature, no inline backticks).
The signature moves into a fenced code block on the
line below — visible to readers, invisible to the
sidebar TOC.
Before:
### `module_desktops <command> [de=<name>] [tier=<tier>] [arch=<arch>] [release=<release>]`
After:
### module_desktops
```text
module_desktops <command> [de=<name>] [tier=<tier>] [arch=<arch>] [release=<release>]
```
Same treatment for the Common pitfalls subheaders, the
parser helper section header, and the common.yaml /
'List and JSON list modes' subheaders — drop the inline
backticks so the sidebar formatting is consistent.
No content changes; this is purely a sidebar-rendering fix.
Tables in the developer guides use the first column for identifiers (field names like 'display_manager', package names like 'gnome-control-center'). When the column was narrow, mkdocs material was wrapping the identifier between letters — 'display_manage' / 'r' — which was unreadable. Add a CSS rule that says: in any table, if the first column's cell contains a <code> element, don't wrap that code. The rule is scoped to <code> in the first cell so prose tables (where the first column might be a sentence) are unaffected. The result is that schema tables auto-size their first column to fit the longest identifier without wrapping mid-word, while keeping the rest of the columns flexible.
The mkdocs config enables linenums globally for every fenced
code block via pymdownx.highlight, which doubled up with the
inline '1. 2. 3.' step prefixes inside the install / remove /
upgrade-downgrade lifecycle blocks. The result was a left
gutter of 1..N alongside the inline 1. 2. 3. on every line —
two parallel numbering systems competing for attention.
Override per-block with `{ .text linenums="0" }` on the three
lifecycle code fences. The inline step numbers are the
canonical step IDs (referenced from the prose around them);
the auto gutter was redundant.
Other code blocks in the doc keep the global gutter — only
the lifecycle ascii-art blocks change.
igorpecovnik
force-pushed
the
developer-guide-desktops
branch
from
39e956f to
2b50f20
Compare
The Top-level fields table at line 112 links to '#tier-overrides',
but the heading 'tier_overrides' slugifies to 'tier_overrides'
under Python-Markdown's default slugifier (underscores are
preserved as part of the word-character class). The link
silently 404s when clicked.
Add an explicit anchor: `### tier_overrides {#tier-overrides}`.
This is the same pattern already used for the Lifecycle: install
heading further down the file.
Verified the other internal fragment link in the same table —
`#tier-blocks` for the heading `### Tier blocks` — slugifies
correctly to 'tier-blocks' (whitespace becomes the separator),
so it does NOT need an explicit anchor and is left alone.
The other two internal fragment links in the file
(`#yaml-schema` from the 'Adding a new desktop' walkthrough and
`#lifecycle-install` from the bash module API table) both
resolve correctly already.
Adds a "Matrix audit automation" section to the desktops developer guide describing the weekly GitHub Actions workflow that audits the YAML matrix and opens bot PRs for drift. Covers: - the two drift classes (missing releases, package holes) and why the deterministic scanner + LLM applier split exists - audit.py report shape, armbian/build dependency, and flags - audit_prompt.py constraints pinned into the Claude prompt - maintenance-desktop-audit.yml triggers, concurrency, each step, the claude-code-action tool allow-list required for edits to actually land, and the execution-log artifact used for diagnosing zero-edit runs - permissions block - a maintainer review checklist for incoming draft bot PRs
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/Developer-Guide_Desktops.md`:
- Around line 871-873: The fenced code block containing "# AutomaticLoginEnable
= true" lacks a language tag and triggers MD040; update that fenced block (the
triple-backtick block around the commented config line) to include a language
identifier such as ini (or text) so it becomes ```ini ... ``` ensuring the
static analyzer no longer flags the block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 017d8e24-5689-4c13-b0ad-f8134e05b133
📒 Files selected for processing (3)
docs/Developer-Guide_Desktops.mddocs/css/armbian-extra.cssmkdocs.yml
✅ Files skipped from review due to trivial changes (2)
- mkdocs.yml
- docs/css/armbian-extra.css
Adds a row for `preferences` to the custom-repo schema table plus an explainer on priority thresholds, the generated stanza shape, and the parse_desktop_yaml.py validation behavior. Matches the configng change that introduces the field.
4 tasks
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/Developer-Guide_Desktops.md`:
- Around line 169-173: The fenced code block that contains the apt pin stanza
(the lines starting with "Package: *", "Pin: release o=<origin>, n=<suite>",
"Pin-Priority: <priority>") is missing a language identifier and triggers MD040;
update the opening fence to include an appropriate identifier (e.g., change ```
to ```ini or ```text) so the block is typed as ini for config formatting
consistency.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dc7fff8a-2eaa-4560-b34b-e4c61504565c
📒 Files selected for processing (1)
docs/Developer-Guide_Desktops.md
Schema table gains rows for the two optional fields introduced by configng, with a bianbu-flavored explainer for when they apply (frozen per-release snapshots, non-default component set).
Adds the `mode=build` parameter to the command synopsis and the install lifecycle table. Each step is now tagged: [B] = runs in both modes (build + runtime) [R] = runtime-only (skipped when mode=build) Explains when/why mode=build is used (image-build time, no user) and how the first boot inherits skel + graphical.target. Matches armbian/configng#859 (implementation) and armbian/build#9683 (build framework consumer).
- Document the community tier in the status field (editorial label joins supported / community / unsupported). - Rename DESKTOP_SUPPORTED -> DESKTOP_AVAILABLE throughout, explain it is the computed release+arch-declared axis, distinct from editorial status. - Document parse_desktop_yaml.py's --filter available|unavailable|all and --status <csv> flags, plus the reshaped JSON list shape. - Document module_desktops supported's filter= and status= params. - Note the short menu slot allocation (*01-*04) used for community [CSC] DEs, and that unsupported DEs stay out of the menu. - Refresh the audit.py skipped_desktops example now that community is its own tier (only unsupported DEs are skipped).
…ase list Four corrections after the build framework / CI work: 1. Browser virtual table was stuck on a pre-apt.armbian.com draft where noble and plucky both used epiphany-browser on every arch. Reality: amd64 uses google-chrome-stable, arm64/armhf use chromium from apt.armbian.com (Ubuntu's chromium deb is a snap-shim), Debian riscv64 uses firefox-esr, Ubuntu riscv64 falls back to epiphany-browser. Also document the loong64/sid entry and drop the plucky block entirely — plucky is EOS, resolute replaced it. 2. tier_overrides example was built around plucky. Replace with the current common.yaml shape: arch-wide strip of armbian-imager (armhf/riscv64/loong64) at mid, arch-wide strip of 'code' (armhf pre-t64 .deb + no riscv64 upstream) at full, and the current per-release thunderbird-on-armhf-or-riscv64 holes. 3. Remove lifecycle step 9 was documented as 'pkg_remove → apt-get autopurge'. The remove path now calls apt-get purge directly after filtering out any package apt flags as essential-breaking from a dry-run. Update the step list and add a paragraph explaining why autopurge was dropped (t64-era orphan-cascade into e2fsprogs) and why a dry-run-filter is still needed (some base images ship without e2fsprogs, so the DE install pulls it in and the purge list would otherwise target it). 4. Release list in overview, schema table, packages_uninstall pitfall, and audit report example all mentioned plucky. Replace with resolute/forky/sid/jammy to match the actual release set the inventory declares in 2026.
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
1 participant
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 technical reference for the desktop submodule in configng (
tools/modules/desktops/). Aimed at developers adding a new desktop, modifying the install pipeline, or integrating the YAML-driven desktop API from another tool. End-user docs for installing a desktop witharmbian-configcontinue to live under ARMBIAN CONFIG.Coverage:
preferencespin list) with worked examples (xfce.yaml,kde-neon.yaml,common.yaml)parse_desktop_yaml.pyCLI surface — allDESKTOP_*variables emitted, validation behavior,--list/--list-jsonmodesmodule_desktops,module_desktop_yamlparse,module_desktop_supported,module_desktop_repo,module_desktop_branding,module_desktop_getuser,module_update_skel,module_appimage)_desktop_in_containersemantics)maintenance-desktop-audit.yml) that scans the YAML matrix againstarmbian/build's supported releases and the Debian/Ubuntu archives, hands findings to Claude Code, and opens a draft bot PR. Coversaudit.pyreport shape,audit_prompt.pyconstraints, every workflow step (including theclaude-code-actiontool allow-list required for edits to land and the execution-log artifact for diagnosing zero-edit runs), permissions, and a maintainer review checklist for incoming bot PRssigned-byAPT sourcesFiled under ARMBIAN BUILD FRAMEWORK alongside Extensions, since it documents an internal/developer API rather than end-user steps.
Paired with configng PR armbian/configng#838, which adds the optional
repo.preferencesfield for APT pin preferences (used by bianbu for SpacemiT's K1 RISC-V archive).Test plan
mkdocs serverenders the new page under ARMBIAN BUILD FRAMEWORK → Desktopspreferencesrow with its explainerDocumentation website preview will be available shortly:
Open WWW preview
Documentation website preview will be available shortly:
Open WWW preview