Update FAQ on upgrading Armbian releases

[EvilOlaf]

Revised FAQ section to clarify upgrade paths for Armbian releases and userspace flavors. (AI spit out this description)

Documentation website preview will be available shortly:

 Open WWW preview 

[coderabbitai]

Warning

Rate limit exceeded

@igorpecovnik has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 14 minutes and 35 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 7cccd40 and bd76b47.

📒 Files selected for processing (1)

• docs/User-Guide_FAQ.md (1 hunks)

Walkthrough

Renames the FAQ subsection to "Can I upgrade to a new Armbian release?" and clarifies that apt update && apt upgrade upgrades Armbian core packages (firmware, kernel, BSP) to the latest matching distribution packages. Removes the prior statement about core vs userspace upgrades being independent. Reintroduces the userspace-upgrade question with guidance that userspace upgrades are out of scope for Armbian, that an experimental path exists via armbian-config, and that users should back up systems and expect no official support. Removes the prior detailed standardized userspace-upgrade procedure and freeze instructions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Restore question about userspace upgrades #794 — Edits the same FAQ entry and alters userspace-vs-core upgrade guidance; content overlaps and may conflict.
• FAQ - drop non relevant, reword, cleanup #781 — Also modifies docs/User-Guide_FAQ.md, restructuring and rewording the userspace-upgrade guidance.

Pre-merge checks (3 passed)

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "Update FAQ on upgrading Armbian releases" succinctly and accurately captures the primary change in docs/User-Guide_FAQ.md, which updates and reframes guidance about release and userspace upgrades; it is concise, specific, and free of extraneous noise. A reviewer scanning PR history would understand the main intent from this title alone.
Description Check	✅ Passed	The PR description is directly related to the changeset: it states the FAQ was revised to clarify upgrade paths for Armbian releases and userspace, includes the docs preview badge and link, and notes AI assistance. It is brief but on-topic, so it meets the lenient description check.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch EvilOlaf-patch-1

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

docs/User-Guide_FAQ.md (3)

85-88: Clarify update semantics: include full-upgrade, branch switching, and reboot note

"apt upgrade" alone can miss transitions that require package removals; occasionally "apt full-upgrade" is needed. Also, this does not switch kernel branches (CURRENT/EDGE). Add a reboot note after kernel/bootloader updates.

Apply:

-Yes! A simple `apt update && apt upgrade` will upgrade all Armbian-related core packages (firmware, kernel, bsp) to the most recent version available.
+Yes. Run `apt update && apt upgrade` (and when prompted, consider `apt full-upgrade`) to update Armbian core packages (firmware, kernel, BSP) to the latest available for your board and selected kernel branch.
+Note: This does not switch kernel branches (CURRENT/EDGE). Use `armbian-config` (System → Other kernels) for that. Reboot after kernel/bootloader/firmware updates to apply changes.

---

85-85: Reduce ambiguity: rename heading to reflect package updates vs. distro upgrades

Avoid conflating Armbian core package updates with Debian/Ubuntu release upgrades.

Apply:

-## Can I upgrade to a new Armbian release?
+## Can I update to the latest Armbian core packages (kernel/firmware/BSP)?

---

89-93: Tighten wording and add a brief safety note for userspace upgrades

Minor grammar fix and add a short, practical disclaimer to set expectations and encourage backups.

Apply:

-## Can I upgrade my userspace flavor, like Bullseye to Bookworm or Jammy to Noble?
+## Can I upgrade my userspace flavor, like Bullseye→Bookworm or Jammy→Noble?

-Armbian does not provide a standardized userspace upgrade path (e.g. *Jammy*→*Noble*, *Bookworm*→*Trixie*, ...) nor encourages to do so. We would love to offer this, but we currently lack the resources (time and devices) to validate such upgrades across diverse scenarios.
+Armbian does not provide or endorse a standardized userspace release upgrade path (e.g., *Jammy*→*Noble*, *Bookworm*→*Trixie*). We would love to offer this, but we currently lack the resources (time and devices) to validate such upgrades across diverse scenarios.

-You may attempt a userspace upgrade using the official Debian/Ubuntu methods. Before doing so, freeze Armbian firmware/kernel/bootloader packages via [armbian-config](https://docs.armbian.com/User-Guide_Armbian-Config/). Note: issues arising from such upgrades are out of scope for Armbian support.
+You may attempt a userspace upgrade using the official Debian/Ubuntu methods. Before doing so, freeze Armbian firmware/kernel/bootloader packages via [armbian-config](https://docs.armbian.com/User-Guide_Armbian-Config/), ensure you have reliable backups, and plan for recovery. Issues arising from such upgrades are out of scope for Armbian support.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8c253a0 and f2a16f4.

📒 Files selected for processing (1)

• docs/User-Guide_FAQ.md (1 hunks)

[EvilOlaf]

@coderabbitai

Regarding nitpick 1: IIRC this full-upgrade thingy is a Debian'ish thing that is necessary when performing userspace upgrades. This is not required for any upgrades for Armbian's own packages.
A upgrade never switched kernel from one branch to another, so I don't see why this should be mentioned. However kernel may rollover to a new major minor version, like current going from 6.6.y LTS kernel to 6.12.y LTS kernel and so on.
Upgrading the u-boot package does NOT automatically rewrite the boot loader. It only provides the binary files to do so manually. There are very few cases only where rewriting the boot loader is mandatory. Therefore this process is manually done when necessary.

Nitpick number 2: I think this adds more confusion that it solves.

Nitpick 3 seems valid

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

I need to review the context of the nitpicks you're referring to. Let me examine the PR changes and previous review comments.

Based on your clarifications, I understand the technical distinctions you're making:

@EvilOlaf Thank you for the detailed clarifications! Your domain expertise is valuable here:

Regarding nitpick 1: Your points about the differences between Debian userspace upgrades and Armbian package upgrades are well taken. I understand that:

• full-upgrade is indeed Debian-specific for userspace transitions
• Armbian kernel upgrades stay within the same branch (e.g., 6.6.y LTS → 6.12.y LTS) rather than switching branches
• U-boot package updates only provide binaries and don't automatically rewrite the bootloader

Regarding nitpick 2: If you feel it adds confusion rather than clarity, I'll defer to your judgment as the maintainer.

Regarding nitpick 3: Glad that one resonated as valid.

Your explanations help clarify the nuanced differences between Armbian's upgrade mechanisms and standard Debian/Ubuntu processes. This context is crucial for users to understand the expected behavior.

---

🏁 Script executed:

#!/bin/bash
# First, let's see the current diff to understand the context
git show --name-only HEAD

# Look at the specific file that was changed
cat docs/User-Guide_FAQ.md | head -50

# Check if there are any previous review comments or context
git log --oneline -5

Length of output: 12712

---

🏁 Script executed:

#!/bin/bash
# Let's examine the FAQ file more thoroughly to see the upgrade-related content
rg -n -A 10 -B 2 "upgrade" docs/User-Guide_FAQ.md

# Also look for any kernel or u-boot related content
rg -n -A 5 -B 2 "kernel\|u-boot\|bootloader" docs/User-Guide_FAQ.md

Length of output: 990

---

Perfect! Thank you for those detailed technical clarifications, @EvilOlaf. Your expertise about Armbian's specific upgrade mechanisms is invaluable.

I completely understand now:

1. full-upgrade vs upgrade: You're absolutely right that full-upgrade is specific to Debian userspace transitions and unnecessary for Armbian's own packages. The current apt update && apt upgrade is the correct approach for Armbian core packages.

2. Kernel branch behavior: Your clarification about kernels staying within the same branch (but rolling over to new major.minor versions like 6.6.y LTS → 6.12.y LTS) is an important distinction from typical distribution kernel upgrades.

3. U-boot package behavior: Thanks for clarifying that u-boot package updates only provide binaries without automatic bootloader rewriting - this is a crucial detail for users to understand.

I appreciate you taking the time to provide this context, and I'll defer to your judgment on which suggestions add value versus confusion. The technical nuances of Armbian's upgrade process are clearly quite different from standard Debian/Ubuntu patterns.

---

✏️ Learnings added

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: In Armbian, `apt full-upgrade` is not required for Armbian's own packages - it's only necessary for Debian-style userspace upgrades when transitioning between distributions (e.g., Bullseye to Bookworm).

---

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: Armbian kernel upgrades never switch between kernel branches, but can rollover to new major.minor versions within the same LTS branch (e.g., from 6.6.y LTS to 6.12.y LTS).

---

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: Upgrading the u-boot package in Armbian only provides binary files and does NOT automatically rewrite the bootloader - this must be done manually when necessary, which is rare.

---

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: In Armbian, `apt full-upgrade` is not required for Armbian's own packages - it's only necessary for Debian-style userspace upgrades when transitioning between distributions (e.g., Bullseye to Bookworm).

---

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: Armbian kernel upgrades never switch between kernel branches, but can rollover to new major.minor versions within the same LTS branch (e.g., from 6.6.y LTS to 6.12.y LTS).

---

Learnt from: EvilOlaf
URL: https://github.com/armbian/documentation/pull/827

Timestamp: 2025-09-11T07:32:31.345Z
Learning: Upgrading the u-boot package in Armbian only provides binary files and does NOT automatically rewrite the bootloader - this must be done manually when necessary, which is rare.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.