Details
- Reviewers
bcr grahamperrin carlavilla - Group Reviewers
Doc Committers - Commits
- R9:fb42d9b2fb16: Handbook-Cutting edge: Add pkgbase information to the chapter
Diff Detail
- Repository
- R9 FreeBSD doc repository
- Lint
Lint Skipped - Unit
Tests Skipped - Build Status
Buildable 65477 Build 62360: arc lint + arc unit
Event Timeline
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.
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1126 | We try to avoid teh use of "you" in the documentation in favor of a more neutral writing style. Next sentence: The pkgbasify does not check for this and it is the responsibility of the user to ensure that enough space is available before running the migration. | |
| 1154 | Create a folder for custom pkg repository config files if there is none present already. | |
| 1160 | Create a pkg repository configuration file called FreeBSD-base.conf for the pkgbase repository | |
| 1179 | ... , switching to the newer branch is needed then. | |
| 1227 | To upgrade the System, change the configuration file according to the desired release, and run: | |
| 1243 | When running ZFS, consider ... | |
| 1249 | Use this boot environment to start the system as it was before the update if something goes wrong. | |
| 1263 | Set the environment variable ABI to upgrade the major version. | |
| 1269 | s/you can run/run/ | |
| 1274 | After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary. | |
| 1288 | Reboot, and the system will be back to the state before upgrading. | |
| 1291 | Manually building pkgbase and publishing it on the local network | |
| 1292 | s/your own/custom/ | |
| 1299 | s/you would like/for the release/ | |
| 1306 | s/You should set/Set/ | |
| 1307 | s/for/for an/ | |
| 1313 | When building frequently, consider using devel/ccache to speed up subsequent builds from the cache. | |
| 1315 | s/on the version you build/on the version built./ | |
| 1317 | s/Network/network/ | |
| 1327 | s/If you are/When/ | |
included the submitted changes from bcr and grahamperrin, thank you for your suggestions
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1173 | Non-base. An introduction to FreeBSD-kmods belongs elsewhere (not in a chapter for base). | |
Sorry, I didn't see this. Yes, I have had it listed already on my doc tracking checklist. This is a huge part of it, please look it over and I would love to hear suggestions. I don't think I've ever made a checklist before.
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1124 | Maybe refer to the manual page; https://reviews.freebsd.org/D51594. | |
| 1135 | https://reviews.freebsd.org/D51594 for pkgbasify in base. https://wiki.freebsd.org/WantedPorts#O-P for a port. | |
| 1155 | /usr/local/etc/pkg/repos/ might be a non-standard path for a file to specify the FreeBSD-base repo. Also, there's the question of whether to use a single file for multiple repos (the FreeBSD-kmods precedent). From https://wiki.freebsd.org/Releng/15.0ISSUES#assigned:
| |
| 1216 | Add stable/15 – expected soon, https://www.freebsd.org/releases/15.0R/. | |
| 1246 | Will base_latest be appropriate for 15.0-ALPHA1? It'll not be appropriate for 15.0-RELEASE. Also: | |
| 1261 | ||
| 1283 | ? | |
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1103 | Some readers will interpret this as freebsd-update becoming unsupported. Maybe truer to state that freebsd-update will not be usable. From https://wiki.freebsd.org/Releng/15.0ISSUES#assigned:
| |
| 1241 | With or without boot environments: it's probably sensible to also have a list of non-base packages. Something like: pkg prime-origins | sort -u > /var/tmp/pkg-prime-origins.txt | |
| 1260 | Thoughts:
| |
| 1273 | Users who have no fallback may wonder how to proceed if something breaks. Direction to https://www.freebsd.org/support/ will be simplest. | |
| 1304 | Can be a link. | |
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1253 | Maybe mention that examples assume AMD64. (Users of other platforms/architectures might copy what's written, without realising that it's not applicable.) | |
| 1318 | I wouldn't use FreeBSD in the name of a file for a repo that is not provided by the FreeBSD Project. YMMV | |
| 1343–1345 | One sentence per line. | |
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1137 | ||
added some thoughts on some comments
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1155 | In /etc/pkg/FreeBSD.conf it is stated, that you should not modify this file, but create a file in /usr/local/etc/pkg/repos/FreeBSD.conf | |
| 1216 | how would that path look like? | |
| 1283 | 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. | |
| 1343–1345 | I don't think this was part of my original changes, but i will change that too. The full chapter "Tracking for multiple Machines" wasn't part of this review before. | |
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.
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1217 | s/System/system/ | |
| 1321 | s/cpu/CPU/ | |
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.
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
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1115 | 14.0 is a supported upgrade from path from 12.4-RELEASE or 13.2-RELEASE, not from 13.3-RELEASE or greater. | |
| 1121 | Begin the sentence with either:
| |
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1172–1215 | It's normal to have ${VERSION_MINOR} (not a specific minor version) in the repo config. FreeBSD-kmods is separate from pkgbase. | |
| documentation/content/en/books/handbook/cutting-edge/_index.adoc | ||
|---|---|---|
| 1172–1215 | On closer inspection, the row for releng/14.1 should be removed. It's no longer twice daily; note that https://pkg.freebsd.org/FreeBSD:14:amd64/base_release_1/?C=M&O=D has nothing more recent than 2025-02-21 (see https://www.freebsd.org/security/unsupported/). | |
@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.
Changed some recommendations from grahamperrin, thank you all for your help, i am looking forward to seeing this committed!
Thanks @carlavilla for committing this.