Improve guidance on development/testing #136
Conversation
Readme.md
Outdated
| ## Testing | ||
| ### Testing on PlayOS hardware | ||
|
|
||
| Changes such as NixOS upgrades, or to anything else that directly interacts with system hardware may necessitate testing on an actual machine. To do so, build a live system: |
There was a problem hiding this comment.
Two comments:
- There is a third possibility that sits between testing on QEMU and a physical machine: A VM like VirtualBox, which can simulate a system more fully, including the installer, Grub and A/B partitions.
- The live system is very useful, but sometimes it's necessary to install a system.
There was a problem hiding this comment.
Mentioned these points in:
Amend readme with additional details
It isn't clearly explained when to use a live system vs a complete installation, because it's not really clear to me 😅. Not sure how important it is to go into such details. I would think the nature of a particular thing being tested would draw us to one of the options.
There was a problem hiding this comment.
Not sure how important it is to go into such details. I would think the nature of a particular thing being tested would draw us to one of the options.
I agree, I wanted to point these out because the added instructions initially were very specifically saying to use a live system, which could be misguiding at times.
It isn't clearly explained when to use a live system vs a complete installation, because it's not really clear to me
As you say, an exhaustive characterization might be hard, but there are some obvious cases, based around the fact that the live system has no A/B partitions and entirely ephemeral storage. So:
- Testing anything to do with the installer requires a full system
- Testing anything to do with A/B systems requires a full system
- Testing anything that spans past one boot (e.g. "Full HD" settings) requires a full system
build
Outdated
| - Status console: ctrl-alt-f8 | ||
| - Graphical UI: ctrl-alt-f7 | ||
| - Toggle controller: ctrl-shift-f12 |
There was a problem hiding this comment.
These are not so much VM shortcuts, maybe move to a separate section?
The manual also explains these, should we link it more prominently?
There was a problem hiding this comment.
These are not so much VM shortcuts, maybe move to a separate section?
I'm not sure I addressed this point in the way you meant, but I renamed the section:
Rename shortcut section in VM hints
Added a link to the manual:
Link user manual in main readme
There was a problem hiding this comment.
Toggling the controller works just fine for me with the regular key combination, also in QEMU. Does it not for you?
I was thinking to just move the sendkey explanation to the block above and let the PlayOS shortcut explanations stand on their own.
controller/Readme.md
Outdated
| @@ -14,9 +14,99 @@ PlayOS controller is an OCaml application that manages various system tasks for | |||
| - `server/`: main application code | |||
| - `bin/`: binaries to start a dev server | |||
|
|
|||
| ## Prerequisites | |||
| Since PlayOS uses `Connman` for managing networks, it must be configured on your system. | |||
| Replace your NetworkManager config with the following (remember to fill in `<your-host-name>`): | |||
There was a problem hiding this comment.
I have a much shorter config on my own machine (I use connman regularly/permanently), was this one necessary for you to use in full?
Maybe also good to note that this assumes NixOS, while it should be possible to build PlayOS on another Linux distro using just nix.
There was a problem hiding this comment.
I don't remember the details of why my config is so long, but it very well might contain unnecessary things. Could you share yours?
There was a problem hiding this comment.
I think this should be enough (it is, I can use the controller like this):
networking = {
hostName = "foo";
wireless.enable = true;
networkmanager.enable = false;
};
services.connman = {
enable = true;
networkInterfaceBlacklist = [ "vboxnet" "zt" ];
};
- Mention the possibility of setting up a VirtualBox VM - Mention creating an installer
|
@krksgbr Would you mind if I take your additions and revise the document on the basis of it? I would push some changes to this PR and you can tell me whether the new explanations and structure match your intentions. |
Sure, feel free to do that. |
krksgbr
added
details needed
Break apart and add overview items to make easier to digest.
This configuration seems to have been taken from the PlayOS network configuration itself and contains several specific configurations that should not be required on the host.
Only the virtual console key combinations require using the QEMU monitor and sendkey, as they would otherwise act directly on the (Linux) host.
knuton
added
reviewable
|
Thanks! Good for me as well. |
Some improvements to documentation, prompted by @stoeffel's comment in #130 as well as coming back to PlayOS after a long break and needing to remember how to do certain things.
Checklist
[ ] Changelog updated[ ] Code documented[ ] User manual updated