[PATCH docs 0/2] software updates: improve user-facing update reference

[PATCH docs 0/2] software updates: improve user-facing update reference

[Nicolas Frey]

more info in the respective patches.

This came up quite a lot in enterprise support (often in combination
with unattended-upgrades, perhaps an addition for another patch?) to
the point where @Laurentiu and I had discussed improving the docs for
this.

Note that similar patches should/will be sent for the other products
as well, though I've held back on that in order to gather feedback
on this series.

pve-docs:

Nicolas Frey (2):
  software updates: use apt instead of apt-get
  software updates: add warning about using apt upgrade

 system-software-updates.adoc | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)


Summary over all repositories:
  1 files changed, 7 insertions(+), 3 deletions(-)

--
Generated by murpp 0.12.0

[PATCH pve-docs 1/2] software updates: use apt instead of apt-get

[Nicolas Frey]

and use full-upgrade instead of dist-upgrade.

although in pveupgrade we still use `apt-get dist-upgrade`, the user
facing doc should use apt, as:
* apt-get is normally used if you want a stable interface, e.g. for
scripts
* if {apt,apt-get} upgrade is run instead of {apt,apt-get} dist-upgrade,
the potential for a partially-upgraded package state is lower with apt,
as it can install new packages - if needed - to satisfy dependencies

full-upgrade is used as it is the preferred term for apt (see `man
apt`). also, it isn't *only* used to upgrade between dist releases, so
full-upgrade is clearer

As a reference to these claims, see:
https://lists.ubuntu.com/archives/ubuntu-users/2025-September/314942.html

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 system-software-updates.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/system-software-updates.adoc b/system-software-updates.adoc
index e6bf356..32afac1 100644
--- a/system-software-updates.adoc
+++ b/system-software-updates.adoc
@@ -9,15 +9,15 @@ Proxmox provides updates on a regular basis for all repositories. To install
 updates use the web-based GUI or the following CLI commands:
 
 ----
-# apt-get update
-# apt-get dist-upgrade
+# apt update
+# apt full-upgrade
 ----
 
 For occasionally upgrading Ceph to its succeeding major release, see
 xref:sysadmin_package_repositories_ceph[Ceph Repositories].
 
 NOTE: The APT package management system is very flexible and provides many
-features, see `man apt-get`, or <<Hertzog13>> for additional information.
+features, see `man apt`, or <<Hertzog13>> for additional information.
 
 TIP: Regular updates are essential to get the latest patches and security
 related fixes. Major system upgrades are announced in the {forum}.
-- 
2.47.3

[PATCH pve-docs 2/2] software updates: add warning about using apt upgrade

[Nicolas Frey]

as it has increasingly come up in enterprise support and is generally an
easy foot gun for people coming from other Debian-based distros.

See commit 2eaf8334 for further reference.

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 system-software-updates.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/system-software-updates.adoc b/system-software-updates.adoc
index 32afac1..6b30aff 100644
--- a/system-software-updates.adoc
+++ b/system-software-updates.adoc
@@ -13,6 +13,10 @@ updates use the web-based GUI or the following CLI commands:
 # apt full-upgrade
 ----
 
+WARNING: As {PVE} uses a rolling release model on top of Debian, performing an `apt upgrade`
+may result in a partially-upgraded or broken package state. This is because `apt full-upgrade`
+can also remove existing packages to satisfy dependencies if needed, while `apt upgrade` cannot.
+
 For occasionally upgrading Ceph to its succeeding major release, see
 xref:sysadmin_package_repositories_ceph[Ceph Repositories].
 
-- 
2.47.3