How to update documentation page got changed and lacks the important information

Here is the current version of the page: How to update | Qubes OS

And here is the August 2nd, 2022 version of the page: How to update | Qubes OS

The “command-line interface” section is lacking the actual commands being listed, in the current version.

Why did such a change occur in the docs?

because adw has changed it https://github.com/QubesOS/qubes-doc/commits/master/user/how-to-guides/how-to-update.md

Yeah, seems like it: Revert "Add warnings and mitigation for QubesOS/qubes-issues#6585" · QubesOS/qubes-doc@5ebedc5 · GitHub

May I ask why the directions for the commands got removed? @adw

The section that was removed dealt with #6585.
The section that remains is exactly what was there before.
I think that “advanced users” would be able to apply those states
without the full commands being given.
If you disagree, put in a PR with the change you want to see. (you can
copy from deleted section 3. and 4.)

Not sure why the section got removed. I was simply following the command line commands since I like using them instead of the GUI tool.

I simply do not understand why remove the exact forms of the command. Now you are forcing the users to read the documentation pages for qubesctl and the salt formulae (which are arcane as they are).

Interested users would read the man pages for it anyways. But the users who want to do the updates on the command line and make it quick (without spending an hour or so wrapping their heads around the documentation) would make use of the commands explicitly states as before.

I have been checking that page from time to time to refresh my memory on the commands.

You obviously disagree, so put in a PR with the change you want. There
are instructions on the page you referenced.

You just linked to the answer to your own question. :slight_smile: I included the reason in the commit message:

Reason: QubesOS/qubes-issues#6585 has been closed as fixed, and the
update has been in the stable repo for over two weeks.

This was in response to a request from another user:

Edan-Redmind:

@andrewdavidwong I see that your explanation regarding this issue and how to handle it is still on the “How to update” page (How to update | Qubes OS). If the issue is solved then maybe it is best to remove it in order to avoid confusing users who don’t know it is resolved.

Me:

Thank you for the reminder! However, I’m not sure if the fix has migrated to the stable repos yet. If it has not, then stable users will still need the workaround instructions until they receive the update. Usually our bot posts automated comments here when the relevant packages migrate to different repos, but I don’t see any such comments here (yet).

(…about a month later…)

Me:

Ok, since it looks like the update has been in the stable repo for a while now, I’ve removed that text from the doc page.

(This reminds me of a comic strip – I think it was a Ziggy – where he wishes upon a star, but it turns out someone in Toledo just wished for the exact opposite. :smiley: )

The commands were there as a workaround to a specific bug. The specific bug has been fixed (we think), so the workaround is no longer needed.

Obligatory xkcd:

workflow

Because they are no longer necessary. We don’t want to make unnecessary work for users or confuse them into thinking the workaround is still required after the bug it was working around has been fixed.

I don’t think that’s true. The links to those pages are “deep links” (i.e., section anchor links) that take you directly to the required commands. So you don’t actually have to read any more than you did before. You just have to click two links, which I don’t think is too much to ask. (Actually just one, since they’re conveniently right next to each other. :slight_smile: ) Besides, duplicating that content was always intended as a temporary kludge, since content duplication is not a sustainable approach.

I guess maybe you didn’t try clicking either of those links, or maybe the autoscrolling didn’t work for you. When I click on them, it takes me directly to explicit example commands:

update.qubes-dom0

Updates dom0. Example (executed in dom0):

$ sudo qubesctl --show-output state.sls update.qubes-dom0

update.qubes-vm

Updates domUs. Example to update all templates (executed in dom0):

$ sudo qubesctl --show-output --skip-dom0 --templates state.sls update.qubes-vm

If the complaint is about having to click an extra link, remember that you can instead just bookmark the first link, so you only have to click once. :slight_smile:

1 Like