fosslinux / fosslinux/live-bootstrap
Confusing instructions in readme
- Dominant language
- Shell
- Stars
- 750
- Forks
- 62
- PR merge metrics
- No merged PRs in 30d
Description
Readme file states that I should clone this repository in case I won't be using Python:
https://github.com/fosslinux/live-bootstrap/blob/9a268c4c39cae952b268bc86da342be2175f03d4/README.rst?plain=1#L30-L35
It made me thinking that while using Python, `rootfs.py` will download repository contents automatically.
But no, it just throws error.
So lines about repository cloning should be moved above Python mention.
---
Before that, readme said about `--mirror` parameter and about instructions given by using `--help` parameter.
Problems are that:
1. `--help` does not mention `--mirror` parameter. There are only `-m` and `--mirrors`.
2. There are no instructions produced by using `--help` parameter. There is a list of parameters, all of which are optional.
https://github.com/fosslinux/live-bootstrap/blob/9a268c4c39cae952b268bc86da342be2175f03d4/README.rst?plain=1#L21-L22
https://github.com/fosslinux/live-bootstrap/blob/9a268c4c39cae952b268bc86da342be2175f03d4/README.rst?plain=1#L24
I suggest to either add `--mirror` to `--help` or change it in readme to either `-m` or `--mirrors`.
Also it would be nice to actually have instructions, which are guaranteed to produce working `.img` file.
It is nice to tweak various parameters, but first of all at least some working result should be obtained.
---
Regarding running `.img` itself, I tried VirtualBox, which either crashes or hangs at `/kaem.x86`.
Trying it with Bochs as well revealed that it writes to addresses which it shouldn't (MMIO ranges).
No wonder it fails to work.
I like the idea of this project overall, but it looks like its quality needs substantional improvement, both from user-friendliness and technical side before I can call it success.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with README.rst at the referenced lines and inspect rootfs.py's argument parser and --help output. Compare the documented --mirror option with the available -m and --mirrors flags, and verify the documented commands produce an .img file. Treat the VirtualBox and Bochs observations as separate technical issues unless the project confirms they belong in this documentation change.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100