@adw: should we update the docs on creating Windows VMs and installing QWT that are existing for Qubes R4.0, or shoukld we create two new sections? The first possibility would probably make the existing text even longer and more convoluted, so maybe a new text based on the QWT provided by @jevank might be easier to understand.
To all of you: Who could create empty templates for these two issues? I’ll gladly help with filling them up.
I added two reports on Windows 7 and 11. From earlier tests, I saw that Windows 10 behaves exactly like Windows 11, just a bit faster. After all, it is basically the same system, just with a slightly modified desktop.
I’ve just re-read the QWT community doc: there’s a lot of info there - which is great - but it will take a significant amount of work/time to find out what content is still relevant for R4.1 together with the updated QWT tools, vs. what part is outdated.
Having spent a considerable amount of time writing detailed guides/doc a few years ago, and seeing how most of their content hasn’t aged well, maybe there are a few important things to agree upon before you - or anyone - spend a lot of time too:
Should content known to be outdated/non-relevant to the current Qubes OS releases be deleted ? In a perfect world with unlimited resources it’d be nice to have docs for each release but it’ll be much easier to just stick to the current version and scrap old stuff - IMHO.
Should content that isn’t known to work with the current release be preceded by a “This content is untested for R4.1” banner ? (that could be because the instructions didn’t mention what release they applied to and testing to see if they’re still relevant would take time)
Should new content always mention the release they apply to - eg. “Those instructions are for Qubes OS Rx.y” ? (I think it should, rather than trying to find out later on what release the original author used).
Content specific to QWT: since it’s a “fast moving target”, at least for now, decide what to do with the QWT doc; eg.
Add a “banner” at the top of the doc that content might be outdated, and redirect to this wiki page ?
Add banners to sections that are known to be outdated, or unknown to work with R4.1 ?
Temporarily replace the link to the QWT doc with the wiki page, until the doc’s content is fully updated to reflect the current qubes release / QWT version ?
More generally, favour the forum’s wiki functionality over community/official docs to publish community guides and only put links in the community/official docs ? The you-must-send-git-PRs approach proved/proves to be too much of a hurdle for people to contribute stuff ; compare to how easy it is to create a post here for posterity with a “fyi that’s how I solved that, hopes this helps others” (which can then be improved upon and transformed into a wiki guide). It doesn’t help either that even the github qubes-community project, which ought to be much more “relaxed” than the official docs, seems too curated.
Some additional information on my QWT installation in Windows 7 and 11: I transferred the rpm installation file to dom0 and installed it there with sudo dnf install ~/Downloads/qubes-windows-tools-4.1.67-1.noarch.rpm
(no security problem with that, as it is a test system.). The installation of QWT itself could then be started via qvm-start <VMname> --install-windows-tools
The Windows VM then had an additional drive containing the msi installation kit, which could be started and installed QWT.
So the standard way of QWT installation is working without problems for both Windows versions (and probably also for Windows 10, which I did not test).
I would suggest waiting until it’s likely to be more helpful than harmful to regular users. I don’t know whether it’s reached that point already, but sometimes outdated information can be a trap for unsuspecting users.
If I understand correctly, these are all community docs, so it’s not my place to decide, though I’m happy to offer my advice and thoughts. Ultimately, it’s up to the community to decide, though, as the official Qubes documentation policies do not govern the community docs.
If you’re curious how this would be handled if it were in the official docs, here’s our current policy on release-specific documentation:
This isn’t strictly enforced to the “letter of the law.” None of the documentation policies are. We strive to follow the principle of merging PRs that are net improvements, even if they fail to comply with some policies, because the docs are still better off. (This is an instance of not allowing the perfect to be the enemy of the good.) PR #1190 is an example where an exception to the usual release-specific doc policy was made.
We don’t expect to have a new documentation system with support for release-specific docs for a while. (It’s being worked on.) I’m not sure how the community docs are handling release-specific docs. Might be in the same boat.
At any rate, my main piece of advice on this point is that Qubes 4.0 will still be supported until 2022-08-04, so it’d be wise to consider how replacing any 4.0 content (as opposed to merely adding 4.1 content while preserving 4.0 content) might affect users who are still on 4.0 and who might still be relying on that documentation.
One point worth considering is that, with Git-based documentation, nothing is ever truly deleted. It’s always possible to recover previous states of the documentation via the Git history. Granted, this is less accessible to less technical users, but GitHub makes it fairly easy for others to just provide them with a link. PR #1190 is an example where this was used as a quick-and-dirty “poor man’s release-specific docs” solution, which was fine because it’s only temporary until 4.0 reaches EOL.
Also, I would again advise caution about what is considered “outdated/non-relevant to the current Qubes OS releases.” Sometimes, after people upgrade to the new release (in this case, 4.1), they mentally consider all older releases (in this case, 4.0) no longer “current,” even though they are officially still current and supported. I see this happen a lot in the official docs, where people try to replace/delete content that stable users are still relying upon, and I have to actively work to prevent it from happening.
These are the sorts of considerations that we’ve been struggling with for a long time now as we try to figure out the best way to manage release-specific docs. I won’t recapitulate the lengthy discussions here. (Feel free to search them out in the mailing list archives and in qubes-issues if interested.) Where we’ve landed is: status quo policy for now while working toward migrating to Read the Docs.
The community docs are a bit different, though, so the same plan may not apply. It might be easier for the community docs to get away with “lighter” methods of release-specific organization.
I mean, this is really a matter of how the community docs are managed, which is just as much up to you as it is to anyone else. Such is the nature of community-run things. But whatever works best is fine. I don’t think anyone knows a priori whether the forum or GitHub will work better for this. It’s probably best to experiment a bit and just try your best. It also helps to be adaptable. The hard part is producing the content. After that, there’s little risk associated with posting it in the “wrong” place, since that can easily be changed with minimal additional time and work required. (For example, if you try the forum first, but that turns out to be a bad idea for some unforeseen reason, you can probably just copy/paste whatever you have at that point into the GitHub community docs, post a link to the new place in the old thread, and ask the mods to lock the old thread.)
I’ll add that “suboptimal” is better than nothing: well-formatted, typo-free, detailed instructions like most of the official/qubes-community docs take a very large amount of time to write (been there); in comparison the forum makes it easy to contribute quick-and-dirty instructions, which could potentially make their way into a qubes-comunnity or official doc after a few rounds of refining. But an issue with forum posts/guides is visibility - ie. how to search/find them (for instance in hindsight the title I’ve picked for this windows post could be improved). IMHO that’s where it would make sense to link forum posts that are deemed helfpul in the official/qubes-community docs (obviously with a “work in progress / use at your own risks” header); for seemingly such popular tasks as creating a windows qube this will definitely save people some time, rather than loosing time following outdated instructions.
[offtopic - here’s an illustration: the current rpc policy doc isn’t relevant to 4.1; this article describes the new format but it’s not easily found (at least it wasn’t for me) and being almost 2 years old it isn’t clear if something changed while coding 4.1’s policies. A “suboptimal rather than nothing” approach would be to add a quick-and-dirty note at the top of the current doc with a link to the article, until somebody spends much more time reformatting the whole document and dealing with PRs back-and-forth (the “good”/“perfect” but time-consuming approach). I considered sending a short PR but there’s always this idea that official qubes docs are too well written to allow that kind of “kludge” ; what’s your position ?]
Ah, nice - I’ve just read related posts/issues, good to see there’s some progress in that area !
Agreed. Hence our policy of merging net-beneficial PRs even when they fail to conform to the doc style guide.
By all means, feel free to submit PRs to add good links in the “External” section of the doc table of contents. We have always welcomed and encouraged this, though precious few contributors take the time to do it.
I say do it! Again, our position has always been: Don’t allow the perfect to be the enemy of the good. Any PR that is a net improvement to the docs is likely to be merged, even if it makes some things worse, and even if it doesn’t follow all the guidelines. (We have to use our judgement, because some things would be too extreme to allow, but this is the general principle we strive to follow in most cases.)
Also, if this is what you’re going for, please try to communicate that in the PR message. It can be hard to tell the difference between these two types of situations:
Type A: Person never bothered to read any of the doc contribution guidelines, style guide, the rest of the docs, etc. Submitted a bad PR out of ignorance and/or laziness.
Type B: Person knows full well that there are problems with the PR but believes, nonetheless, that it would be a net benefit. Doesn’t have time to do more right now.
Often, people submit PRs with zero commentary or explanation. Just a commit that changes a bunch of stuff, where it’s frequently unclear why anyone would want to make such changes. It would really help if the Type B folks could say a few words to differentiate themselves from the Type A folks so that I don’t reject their PRs due to misaligned expectations and misunderstanding.
I’m stuck by trying to install the new qubes tools.
I startet a disp.VM and made there all the steps from jevank (1-3).
The 4th step stucks and show me: file not found by glob: qubes-packages-mirror-repo/dom0-fc32/rpm/qubes-windows-tools*.noarch.rpm
I’ve just rebuilt QWT and it works fine (although on a fedora-35 build vm, not fedora-34). Are you sure there was no error during building and that you pasted the right instructions ? (it’s easy to mess up copy/pasting - maybe you pasted the same instructions twice ?).
If you’re sure you did everything right, maybe file an issue ?
ok, thanks! That was the point.
The thing is, after I installed it in Windows10, it has no effect no anything.
Maby it’s because I had there the old version of qubes tools?
Or maby it’s because I restored Win10 from the backup made in Qubes 4.0?
Anyway Windows10 crushes after some time (but I think, thats another problem).