[Bug 287662] Handbook updates wrt 'kmods' - proposals

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=287662

--- Comment #5 from Eric <erichanskrs@gmail.com> ---
Created attachment 263418
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=263418&action=edit
patch wrt to the kmods intro & switching to latest

(In reply to Benedict Reuschling from comment #3)

I took the opportunity to make some additional edits.

- introduced the 'kmods' before the switch to latest. It seems 
  more logical to first introduce the 'kmods' and then have it  
  followed by its application when switching from the default 
  quarterly to latest on a -RELEASE.
- the optional parts referring explicitly to 14.2-RELEASE 
  have not been included. The kmods explanation should provide 
  enough information IMO; also, 14.2-RELEASE goes EoL at
  the end of September.

As in my OP already used, changes include the use of  
${VERSION_MINOR} and one .conf file (FreeBSD.conf) for both 
repositories. VERSION_MINOR is documented in pkg.conf(5).
This is in line with the settings as provided by: 
https://cgit.freebsd.org/src/tree/usr.sbin/pkg/FreeBSD.conf.latest?h=stable/14
https://cgit.freebsd.org/src/tree/usr.sbin/pkg/FreeBSD.conf.quarterly?h=stable/14
https://cgit.freebsd.org/src/tree/usr.sbin/pkg/FreeBSD.conf.quarterly-release?h=stable/14

Furthermore, the use of so called magic numbers is to be  
avoided whenever possible, and they require manual adjustment 
when upgrading, for example from 14.3-RELEASE to 14.4-RELEASE. 
We also do not use:
FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/FreeBSD:14:amd64/latest" }

Instead we use:
FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }

A separate 'kmods.conf' file is possible but, IMO not called for in this 
situation. Using one FreeBSD.conf file for both repositories keeps 
repository set ups in close proximity. When changes in configuration 
settings are made it is more likely that the necessary alignment between
FreeBSD and FreeBSD-kmods stays intact.

In my experience users can easily miss an introduced misalignment.
The additional effort put on users to properly use the 
kernel modules in the FreeBSD-kmods repsitory should, in my view,
be kept to a minimum whenever possible. This example of misalignment 
was given as an answer on the forums by a very experienced sysadmin:

Repositories:
  FreeBSD: {
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/latest",
    enabled         : yes,
    priority        : 0,
    mirror_type     : "SRV",
    signature_type  : "FINGERPRINTS",
    fingerprints    : "/usr/share/keys/pkg"
  }
  FreeBSD-kmods: {
    url             :
"pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/kmods_quarterly_3",
    enabled         : yes,
    priority        : 0,
    mirror_type     : "SRV",
    signature_type  : "FINGERPRINTS",
    fingerprints    : "/usr/share/keys/pkg"
  }

While I have no doubt that he would be able to rectify this easily when
confronted with unexplainable results later on; errors stemming from
misalignment may be hard to track down for new, unexperienced and
experienced users alike.

I have adjusted the 'Kmodsflavor' table header:
<blank> | Latest | Quarterly

-CURRENT is not a release or a supported (development) version.
The most recent release branches yield supported release versions; 
similarly the most recent stable branches yield supported development versions.

I don't have any experience in editing FreeBSD documentation, this is my first
attempt.
Please review this patch and make changes where desired.

Kind regards,
Eric

-- 
You are receiving this mail because:
You are the assignee for the bug.