Doc upgrade/downgrade policy #1038
Conversation
- Add section on upgrading/downgrading and boot-order to system.md - Add or update references on upgrading from other pages - boot.md (update ref) - cli/upgrade.md (add ref) - management.md (add ref) [skip ci]
|
Perhaps too chatty documentation? :-) |
There was a problem hiding this comment.
Very well written, comprehensive and instructive! I've given some very minor comments and ideas for improvements. Nothing blocking merge, so this is approved in the state it is now.
The comments for lists apply to all lists in this PR even though I've just commented on the first.
doc/system.md
Outdated
| 1. Download and unpack the release to install. Make the image *pkg* | ||
| bundle available at some suitable URL (FTP/TFTP/SFTP/HTTP/HTTPS). | ||
| 1. Assume the unit has booted the `primary` image. Then running the | ||
| `upgrade` command installs a new image on the `secondary` | ||
| partition. | ||
| 1. As part of a successful upgrade, the boot-order is implictly | ||
| changed to boot the newly installed image. | ||
| 1. Reboot the unit. | ||
| 1. During boot, the unit may [migrate](#configuration-migration) the | ||
| startup configuration inline with newer configuration definitions. | ||
| 1. The unit now runs the new image. To upgrade the remaining partition | ||
| (`primary`), run the same upgrade command again, and reboot. |
There was a problem hiding this comment.
Even though it works, thanks to Markdown, for enumerated lists I'd recommend1 using 1, 2, 3, ... instead of 1, 1, 1, ... and personally I try to avoid closing period for each item. Iirc that was one of the points from Strunk & White ...
Also, for instruction lists like this I'd recommend going for brevity in each item and move any helpful hints to footnotes. Example:
- Download and unpack the release to install, make the
.pkgfile available at some URL2 - Assuming the device has booted from the primary partition, the
upgradecommand will upgrade the secondary partition - ...
For the last item, reboot is really optional, so explain why one may want to reboot anyway. I.e., to verify the upgrade. Also, the second to last item should tie in better with the last, because of the risk of starting a device with a migrated configuration with an older version of Infix. Maybe a warning or caution notice could be added here, possibly replacing one or two items? Like this:
Caution
During boot, the unit may migrate the startup configuration for any syntax changes. It is therefore important that you make sure to upgrade the other partition as well after reboot, of course after having verified your setup.
Footnotes
There was a problem hiding this comment.
Link to GitHub markdown extension for alerts https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
Fixes #1009
Description
Checklist
Tick relevant boxes, this PR is-a or has-a: