Handbook pkgbase upgrade: Split pkgbase major upgrade to use zfs with boot environments, add workaround lock pkg

[lukas.engelhardt_gmx.de]

Summary

Split pkgbase major upgrade to use zfs with boot environments, add workaround lock pkg.
Remove 14.2-Release

[ivy]

documentation/content/en/books/handbook/cutting-edge/_index.adoc

1236

this file won't exist in 15.0-RELEASE. instead, the secteam-managed repository will exist in /etc/pkg.

1361

upgrading from 14 to 15 with pkgbase is not officially supported, since pkgbase is not supported in 14. upgrading from 14 to 15 with freebsd-update is fully supported.

1362

i'm fairly sure this is not true. there is some weird edge case which can result in pkg proposing to remove itself, which does cause pkg to crash if the user types 'y', but this is not the usual situation.

1421

this text seems to duplicate the text above.

[bcr]

Good writeup and having these extra instructions is definitely helpful to have in the handbook. Thanks!
I fixed occurances of you in the text. Other than that, I did not find anything else that needs fixing.

documentation/content/en/books/handbook/cutting-edge/_index.adoc

1232

s/your/the/

also maybe: s/nice/easy/

1233

s/your/the/

1236

s/so it looks like/to look like this/

1258

s/your/a/
s/you would like to upgrade to/to upgrade to/

1264–1266

s/folder/directory/g
s/your/the just created/

1364

s/you need to//

1372

s/to where you mounted your boot environment/to the boot environment mountpoint/

1379

s/to ask/asking/

1384

s/you should remove the lock/remove the lock like this:/

1398

s/If you need some more help, consider getting help from/Consider getting help from ... when experiencing issues.

1401

s/your/the/

Also describe how (the -t option to bectl).

1402

s/you/the system/
s/your/the/

1410

s/your/the/g
s/you might accidentally boot/to prevent accidentally booting/

1432

Whitespace at the end of the sentence here.

[lukas.engelhardt_gmx.de]

Thanks @bcr for your changes, i have to work on that writing style.

@ivy thanky for your quick response, unfortunately not everything is clear to me on how it is supposed to work, i tried to solve it, so please take another look.

[lukas.engelhardt_gmx.de]

documentation/content/en/books/handbook/cutting-edge/_index.adoc

1236

how is the major upgrade supposed to go, or is this not decided yet?

[grahamperrin]

documentation/content/en/books/handbook/cutting-edge/_index.adoc

1212

Needs releng/15.0 plus 16.0-CURRENT options.

For all FreeBSD-base url values:

• pkg+https (not https)
• be prepared for introduction of the pkgbase.freebsd.org repo.

1241

/base_release_${VERSION_MINOR}

might be better.

1284

Link to the issue, instead? Easier to track.

https://github.com/freebsd/pkg/issues/2475

1284

Better link to the issue? Easier to track:

https://github.com/freebsd/pkg/issues/2475

1333–1335

1337–1342

This chunk should probably be earlier.

1337–1342

This chunk should probably be earlier.

1346–1351

Can the subsection of the book be structured to avoid duplication?

[ivy]

documentation/content/en/books/handbook/cutting-edge/_index.adoc

1236

i don't think that's been decided yet as we don't have a supported pkgbase major upgrade path right now, since 15 is the first pkgbase release. i expect it will involve editing the FreeBSD-base.conf (or whatever the file ends up being called) to specify the new release (which is more or less what you're written here), then running pkg upgrade.

if you're trying to document a pkgbase upgrade from 14 to 15... this is not really supported, and the documentation should probably reflect that. at the least, that would involve installing the FreeBSD-set-minimal package, which is new in 15. i haven't tested this and have no idea if such an upgrade actually works.

1241

won't this use the existing release minor, not the minor of the release we're trying to upgrade to?

[ivy]

while you're here, i notice there is some existing text in this page which is wrong:

Starting from 15.0-RELEASE, Base System packages will be the default and officially supported way to both install new FreeBSD instances, and also to update and upgrade between minor and major releases.

this was the original plan, but is no longer the case. distribution sets will remain the default/recommended installation method, and pkgbase is provided as a "tech preview" -- meaning it's supported, but not recommended.

From 15.0-RELEASE onwards, the long-running freebsd-update(8) tool will only be supported on the earlier 13 and 14 release branches.

freebsd-update will continue to be supported for the entire lifetime of stable/15.