man/bootc-rollback: add information about /etc

[jmarrero]

This is just adding the docs added on https://gitlab.com/fedora/bootc/docs/-/merge_requests/90 to the man page.

[cgwalters]

Minor nit, we're not consistently back-ticking filenames, i.e. this should be /etc

[cgwalters]

This sentence is a bit awkward, maybe:

To perform a logical rollback, while still carrying forward changes to local configuration files, use bootc switch to an explicit prior image tag or digest. This acts the same as a bootc upgrade, just with older content.

[cgwalters]

Let's backtick bootc rollback too.

[jeckersb]

I think this is not quite right, because the stuff under docs/src/man is autogenerated. Looks like the flow begins from cargo xtask update-generated which is basically doing:

• cargo xtask manpages
  • which in turn is running cargo run --features=docgen -- man --directory target/man to generate the manpages from the docstrings in the rust src
  • additionally iterates through the files in docs/src/man-md and uses mandown to convert those into manpages and put them under target/man as well
• Runs pandoc on everything in target/man to then turn those into the files in docs/src/man

So really this needs to go into the docstring in the rust source, or we need some better way to include additional sections in the manpage beyond just autogenerating the DESCRIPTION?

[cgwalters]

Ah yes, you're right. Glad you caught that. I guess we probably need to auto-generate loud "Don't edit this file" markers too.

This all said, I was poking at switching to hand-writing the man pages but just extracting the minimal argument docs from the rust code instead. Or maybe we just want a CI test to ensure they're in sync.

[jeckersb]

Looks like you can add things to the EXTRAS section by using after_help on the clap Command: https://github.com/clap-rs/clap/blob/master/clap_mangen/examples/man.rs#L17

[jeckersb]

I pushed a version to my fork which seems to do what we want, incorporating Colin's suggestions. If that looks sane to others we can incorporate it into this PR.

[jeckersb]

Although now that I re-examine it I'm not 100% sold on that solution, because it ends up in the bootc rollback --help output (maybe we want that, maybe we dont?). If we do want it in there, formatting needs tweaked because the 80-char wrapped string in the indoc expands into nice paragraphs in the manpage, but it does not expand nicely on the cli; instead we end up with the hard line breaks:

Change the bootloader entry ordering; the deployment under `rollback` will be queued for the next boot, and the current will become rollback.  If there is a `staged` entry (an unapplied, queued upgrade) then it will be discarded.

Note that absent any additional control logic, if there is an active agent doing automated upgrades (such as the default `bootc-fetch-apply-updates.timer` and associated `.service`) the change here may be reverted.  It's recommended to only use this in concert with an agent that is in active control.

A systemd journal message will be logged with `MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468` in order to detect a rollback invocation.

Usage: bootc rollback

Options:
  -h, --help
          Print help (see a summary with '-h')

Note on Rollbacks and the `/etc` Directory:

When you perform a rollback (e.g., with `bootc rollback`), any
changes made to files in the `/etc` directory won’t carry over
to the rolled-back deployment.  The `/etc` files will revert
to their state from that previous deployment instead.

This is because `bootc rollback` just reorders the existing
deployments. It doesn't create new deployments. The `/etc`
merges happen when new deployments are created.

If you want to save a modified `/etc` file for use after the
rollback: You can copy it to a directory under `/var`, like
`/var/home/User` (for a specific user) or `/var/root/` (for
the root user).  These directories aren’t affected by the
rollback as it is user content.

Going back to the original state from either through a
temporary rollback or another `bootc rollback`, the `/etc`
directory will restore to its state from that original
deployment.

To perform a logical rollback, while still carrying forward
changes to local configuration files, use `bootc switch` to an
explicit prior image tag or digest. This acts the same as a
`bootc upgrade`, just with older content.

[jmarrero]

I am not sure if all man pages content is expected to be on the --help page. But I can see people benefiting from it and also can see it being too much 🤷‍♂️

[jmarrero]

We could point to the doc URL... but then we have to think about RHEL vs Fedora docs?

[cgwalters]

We had a live chat on this; I'm fine with having a relatively long --help but in the more medium term I'd lean towards either (or both!) of:

• Manual man page generation, with CI to check
• Creating a man bootc-upgrade-rollback that has all the details, kind of like man bootup

[vrothberg]

Thanks for adding that to the docs!

Could you add a similar (maybe briefer) note to the fedora-bootc docs? We can xref here for the full details.