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

1246

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

1358

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.

1359

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.

1418

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

1238

s/your/the/

also maybe: s/nice/easy/

1239

s/your/the/

1246

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

1286

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

1292–1294

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

1361

s/you need to//

1369

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

1376

s/to ask/asking/

1381

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

1394

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

1398

s/your/the/

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

1399

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

1407

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

1429

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

1246

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

[grahamperrin]

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

1219

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.

1271

/base_release_${VERSION_MINOR}

might be better.

1311

Link to the issue, instead? Easier to track.

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

1311

Better link to the issue? Easier to track:

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

1360–1362

1364–1369

This chunk should probably be earlier.

1364–1369

This chunk should probably be earlier.

1373–1378

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

[ivy]

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

1246

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.

1271

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.

[lukas.engelhardt_gmx.de]

Thanks @grahamperrin and @ivy for your input, please take a look if i implemented the changes correctly.

[lukas.engelhardt_gmx.de]

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

1219

Can you tell when pkgbase.freebsd.org will be introduced?
16.0-CURRENT is main/base_latest, or should it be its own entry?

1271

i agree, this is especially for upgrading, therefore should be set manually, or i would have to set VERSION_MINOR with env later when upgrading.

1373–1378

moved to preparations

[grahamperrin]

A while ago, probably around August, I began referring to freebsd-update as legacy, because it was commonly understood that it would be "removed or at least neutered" with 15.0-RELEASE.

https://lists.freebsd.org/archives/freebsd-pkgbase/2025-August/000785.html (25th August) quoted from the wiki, at a time when the future of freebsd-update post-15.0 was not totally clear (hence my uncertainty about naming a future tool). Colin helped to clarify, with his removal of a related line on 12th September: https://wiki.freebsd.org/Releng/15.0ISSUES?action=diff&rev1=56&rev2=57.

On 2nd October, Isaac wrote:

I'm in touch with mark about his work on pkgbase-aware freebsd-update and am working on improvements to pkg and pkgbasify in support of his work.

Mid-October:

• Make pkgbasify more flexible · Issue #92 · FreeBSDFoundation/proj-laptop

I lean towards describing an outcome of Mark Johnston's co-work as next generation freebsd-update, although I shouldn't expect that phrase to appear in the FAQ or FreeBSD Handbook.

The notion of version 2 is nice, although I don't expect the tool to be packaged and versioned in this way.

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

1110

The current plan is for freebsd-update to work with pkg.

[grahamperrin]

https://reviews.freebsd.org/D53534#1222869

Can you tell when pkgbase.freebsd.org will be introduced?

From https://www.reddit.com/r/freebsd/comments/1olz899/comment/nmmwup0/?context=1:

pkgbase.f.o isn't up yet because we're still waiting for the new HSMs to be set up. …

[grahamperrin]

Thanks.

I'll pause for now, because I find it difficult to visualise with Phabricator. Clicking Undo does not undo (so, you may see repetition), and so on.

Given the wish to avoid use of the word pkgbase, more word replacements will be necessary.

https://man.freebsd.org/cgi/man.cgi?query=pkgbase&sektion=7&manpath=freebsd-stable for pkgbase(7) in FreeBSD-STABLE redirects to freebsd-base(7) with no mention of pkgbase; and so on. (You might see the word in the online rendering, but not with man 7 pkgbase.)

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

1091

1092–1093

base is kernel + userland, so we need avoid expressions such as kernel and base.

1092–1093

Less use of the word use.

1093–1096

1098–1099

1101–1107

1114

1122–1125

1126–1127

1127–1128

1130

1132–1147

Don't attempt to duplicate the pkgbasify-provided documentation for pkgbasify.

1147

1151

1161

1237–1243

1238–1239

For now, be more assertive about backup.

1266

1269

1273–1275

Whilst FreeBSD Handbook does not normally stray into CURRENT territory, it's worth mentioning 16.0-CURRENT here.

1292–1294

Will it help to link to the manual page for chroot(8)?

1302–1305

1342–1343

1391–1392

If # implies superuser, then pkg update is superfluous.

1391–1392

[grahamperrin]

My current thought is much the same as Sergio's in August:

… we can improve it later in small commits. …

If it helps to commit this review as is: I'll have no objection. My suggested/requested changes can be rolled into a later review.

I'm conscious that builds of the first release candidate of 15.0 are only a week away. It'll be smart to have the Handbook updated during BETA5 (but no pressure from me).

[lukas.engelhardt_gmx.de]

@grahamperrin thank you for your suggestions.
I tried to integrate them to the best of my knowledge.

Sorry, that i was not able to take a look any time sooner, i was busy and haven't found the time to work on this.

If there are no substancial errors or changes i agree we should try to get this out there before 15 release.

[grahamperrin]

Thanks! I'm (blindly) accepting without checking.

[bcr]

I'll bring this into the doc tree. I'll do a few minor textual fixes before committing, but nothing substantial.
Thanks for the update, it's definitely helpful to have accurate information for users on how to work with pkgbase to upgrade when 15.0 RELEASE hits.