Handbook: Jails, add upgrade instructions

[gbe]

Summary

Handbook: Jails, add upgrade instructions.

PR 247927

Test Plan

compile the handbook and review the html output.

[debdrup]

Here's a few nits I noticed.

en_US.ISO8859-1/books/handbook/jails/chapter.xml

538–541 ↗

(On Diff #74447)

I think this needs a bit of wordsmithing - it's unclear whether it's talking about the host or the jail.
If it's about the jail, I believe the example below also needs --currently-running.

543 ↗

(On Diff #74447)

I think you've got an extra space that snuck in just before /here.

545–546 ↗

(On Diff #74447)

I think it would be better to refer to it as "the latest patch level" instead of "a new version", and drop the parenthesis about security updates as patch-levels include both security updates but also errata notices.

[gbe]

• Update the wording in the first new paragraph and remove some whitespaces

[gbe]

Address some comments from @debdrup

[gbe]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

545–546 ↗

(On Diff #74447)

The command examples referring to a new point release of the stable branch, so I would think that speaking of "the latest patch level" would be wrong. What do you think about new paragraph above that one that aims for patch level updates?

[debdrup]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

545–546 ↗

(On Diff #74447)

Well, as an example, 12.2 will start out life as a repocopy of stable/12 to releng/12.2, so I don't think the description of 'a new point release of the stable branch' is the most accurate description, but I clearly misunderstood what the sentence was saying, since I now think understand what you were trying to say. I also think avoiding the phrase 'point release' is a good idea, as it is a bit less well-defined, as I've seen people use it to refer to the X in both 12.X and 12.1pX?

What do you think about "To upgrade the jail to a new major or minor version, first upgrade the host system as described…"?
That makes it clear that it works for both FreeBSD-X and FreeBSD-X.Y.

[gbe]

• Make it more clear that major and minor versions can be upgraded

[gbe]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

545–546 ↗

(On Diff #74447)

I updated the paragraph. I am not the author of the original patch and I haven't used jails that much recently, so your feedback is more than appreciated. :)

[bcr]

Thanks for working on this PR, I think with the changes from @debdrup it is much better now and good to go into the handbook.