Superseded by 8e0b1a1c03a35a5db13e370cb3e62585d3db68e3

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.

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

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

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

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.

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

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.

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

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

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

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.

yup, thanks for the bump.

i think we agreed this change is wrong, can we close the review?

Fix documentation of NOPKGBASE (this got inverted by the rebase)

"building src into packages" > "building packages(7)"

Rebase, resolving conflict from change to -DNOPKGBASE

rebase, resolve conflicts with change to -DNOPKGBASE

Fix bad rebase

rebase

aside from one or two stray instances of .Cm packages this looks good.

use kevan's suggestion for update-packages

fix a straggler

pkg(7) targets -> packages(7), apply ivy's suggestions elsewhere

fix incorrect backslash

attmpt to fix objroot but honestly I don't really understand what I'm reading here.

rebase

I think this patch could use a bit more work than just updating for the -DNOPKGBASE change. It was written before package sets were added and it would be nice if we could leverage those rather than doing fragile regex-based matching.

In D51483#1203665, @cperciva wrote:

Actually, this is going to need some changes now that PKGBASE is the default and there's a new NOPKGBASE option. Should I just take over this patch?

Actually, this is going to need some changes now that PKGBASE is the default and there's a new NOPKGBASE option. Should I just take over this patch?

@ifreund_freebsdfoundation.org Can we land this soon?

Don't hardcode "worldstage"

oops, forgot to switch it on line 729

+ Add an entry for OBJROOT

Looks good but I'd like to avoid having the literal worldstage in two different places if we can

Special thanks to @dch for working on parts of this handbook and @bcr for helping me getting started on how to work with documentation!

Changed some recommendations from grahamperrin, thank you all for your help, i am looking forward to seeing this committed!
Thanks @carlavilla for committing this.

In D51279#1190938, @carlavilla wrote:

@lukas.engelhardt_gmx.de do you want to take a look to latest messages?

I want to make the commit in one hour or so.

@lukas.engelhardt_gmx.de do you want to take a look to latest messages?

In D51279#1190892, @lukas.engelhardt_gmx.de wrote:

… Changed that to "If you want to start building your own pkgbase packets" instead of "To start building custom pkgbase packets". Does that answer your question? If not please specify. …

I'll do the commit in a couple hours.
It's true, we can improve it later in small commits.
And there's a lot of documentation to upgrade related to pkgbase

Thanks bcr. Corected these smaller issues.
I do also think that this should get out there in the handbook and we will be refining smaller parts as they come. Some things might change later, so we might have to change some things here afterwards.

Found two smaller issues.
As far as I can tell, this is as ready as it's going to be. If we find issues afterwards, we can fix those in the handbook, rather than putting more and more stuff into this review.

added some thoughts on some comments

Changing the parts grahamperrin suggested, thanks for your input.

In D51279#1184923, @bcr wrote:

@ziaee Do you think we can commit this as part of your list of doc changes needed for pkgbase? It's a start and I'd rather have something in the handbook that we can commit extension to before we try to add more to an ever growing review. Any thoughts? Do we need more reviewers?

removed kmods description

included the submitted changes from bcr and grahamperrin, thank you for your suggestions

Some sentences should be rewritten to avoid the use of "you". I've made a couple of suggestions towards this. There may be other instances (search for "you" and rewrite accordingly). This often results in the use of active voice (i.e. "Use FreeBSD" instead of "You could use FreeBSD") as a positive side effect.
No more content changes as far as I can tell.

pkgbase (lowercase) throughout, thanks.

I opened https://reviews.freebsd.org/D51916 to make bsdinstall put FreeBSD-base.conf in /etc/pkg as well.

Move to /etc/pkg