Re: I am sick and tired of the poor quality of documentation on FreeBSD

> Nov 21, 2023, 21:30 by steve@sohara.org:
>
>>
>> You did of course read the release notes right ? The rather good
>> documentation provided by the FreeBSD project for each new release.
>> Specifically this section that tells you exactly what to do and why.
>>
>> https://www.freebsd.org/releases/14.0R/relnotes/#upgrade
>>
>> Documentation is only useful if you read it! BEFORE you do things.
>>
>>> Something like this doesn't help!
>>>   Pool 'zroot' has the bootfs property set, you might need to update the
>>> boot code. See gptzfsboot(8) and loader.efi(8) for details.
>>>
>>
>> It's a warning not documentation, heeding it could have saved you
>> much trouble.
>>
>>> I might need to update the boot code!? WTF does that even mean?
>>>
>>
>> It seems pretty clear that you should make sure you understand it
>> and do what is necessary *before* you reboot. The boot code is (as the name
>> implies) the code used to boot the system which has to be able to read the
>> filesystem containing the OS, which it can't if that filesystem has been
>> updated with features that the existing boot code does not support.
>>
>>> I never touched any boot code during installation so I don't even know
>>> what that is! And reading those man pages did NOT help me in any way.
>>>
>>
>> If you had read the release notes you would know what to do, and
>> surely the name "boot code" is sufficiently descriptive as to what it is.
>>
>>> So now I got a box that's borked with this beautiful message after
>>> updating the zroot pool:
>>>
>>
>> AND rebooting without updating the boot code right ?
>>
>>> ZFS: unsupported feature: com.delphix:head_errlog
>>> ZFS: pool zroot is not supported
>>> Can't find /boot/zfsloader
>>> Can't find /boot/loader
>>> Can't find /boot/kernel/kernel
>>>
>>
>> Now you're going to need this article in the forums which a search
>> would have found for you in a few seconds:
>>
>> <https://forums.freebsd.org/threads/upgrade-14-relase-root-on-zfs-reboot-before-update-boot-code-and-stuck-at-efi-shell.91035/>
>>
>> You might want to thank T-Aoki and note the rather more polite way
>> someone else who got themselves into this mess asked for help.
>>

The release engineering and related documentation suck as usual. Polite my ass. I have had it.

I have been on FreeBSD for more than 20 years and always have to deal with shitload of problems on this operating system ONLY due to the lack of documentation.

I read the man pages, I read the forum post, which doesn't help shit when the next crap you run into is this:

  ZFS: unsupported feature: com.klarasystems:vdev_zaps_vs

Nothing should break this bad during a simple upgrade and then have the guy responsible for the documentation to make a fucking blog post about the missing documentation on the website:

https://www.daemonology.net/blog/2023-11-21-late-breaking-FreeBSD-14-breakage.html

"but there are a few last-minute issues which deserve to bedocumented — probably somewhere on the FreeBSD website, but I canpost to my blog much faster and hopefully we'll get these onto the FreeBSDwebsite later."

Oh, and let's not forget this one:

"stand: Fix oversight in updating OpenZFS: Add com.klarasystems:vdev_zaps_v2com.klarasystems:vdev_zaps_v2 is a new feature that the last OpenZFSimport brought in. It needs to be on the list of supported features, butthat update didn't happen so I woke up to a mailbox with multiplecomplaints."

Thank you very much! Amazing work.