Judging from the mailing list discussion, this section needs organized
better. Hopefully, this should do it.
Discussed with: cperciva (it's still ok to organize better)
Details
Details
- Reviewers
dch cperciva ivy olce grahamperrin - Group Reviewers
releng docs pkgbase - Commits
- R9:dce95ff77e20: 15.0/relnote: Organize Upgrading section
Diff Detail
Diff Detail
- Repository
- R9 FreeBSD doc repository
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 77 | We could maybe clean this up like this? | |
Comment Actions
+ mention the releng/15.0 branch in Source Upgrades
+ clean up the giant run on sentance in the beginning of
Package Upgrades
Note:
Package upgrades is still missing actual "pkg upgrade" step from
instructions, maybe any previous step.
This giant run on sentance is still a bit illegible.
Comment Actions
Here are some pictures of what I have so far. If nobody complains I will just commit this because what we have currently is broken judging by the mailing list.
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 72 | This bit belongs in the upgrade-rc section I think? | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 72 | I thought not because it says it's not possible to upgrade using pkg-update, which is never supported for pkg base. If it's supposed to be there, I want to adjust the wording. | |
| 85 | This is a giant run on sentence. It is illegible. I took out the bit about any later branch $qualifier $qualifier. if they can check out any later branch, they can check out the release tag. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 72 | The intended meaning is "you can't just use pkg to upgrade normally because we removed the pkgbase bits which were signed with the pkg keys, leaving only pkgbase bits which are signed with the pkgbase keys which you don't have the fingerprints for". This is fallout from the last-minute repository configuration change. I think pkg-upgrade should probably have just been pkg. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 72 | Ahhh, I'm glad this was brought up! | |
Comment Actions
i wonder if it's worth adding a note about reinstalling ports/packages after upgrading. a lot of people don't seem to understand this and break their system, because they don't know how to become root when sudo isn't working, and the message from freebsd-update is still quite weak even after it was changed recently.
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 62 | what are "distributions"? if this refers to distribution sets (i.e., non-pkgbase installs), i don't think anyone will understand this. i'd suggest something like "Upgrading with freebsd-update" or "Upgrading a system not installed from base packages" or something like that. | |
| 70–71 | a lot of people are using pkgbase on 14; i think it's worth adding an explicit note that upgrading from anything older than 15.0-ALPHA using pkgbase is not supported. (it will probably work, it just hasn't been tested and we don't have any documentation on how to do it; this isn't a huge issue, because only people with expert knowledge of pkgbase should be trying this to begin with.) | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 104 | I only have some wordsmithing for a sentence that sounded slightly awkward to me. Of course, feel free to take it or leave it. | |
Comment Actions
Thank you so much for the reviews. These are tough issues actually.
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 62 | We need a way to describe it that reads simple. | |
| 70–71 | I'm scared that actually this is a huge issue, and I cannot declare that it is not supported to update from one official image to another. I was really hoping someone who Knows What's Up would help with the actual instructions part because I don't. | |
| 104 | Thanks jrm! Your suggestion does read a lot better, but it needs to tell them to read and follow UPDATING. I'll keep chewing on it. We had the previous text for many releases actually. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 104 | It sounds reasonable to refer readers to more details in /usr/src/UPDATING, but phrasing it as "according to the instructions in /usr/src/UPDATING" gives a non-authoritative tone. How about this? Source-based upgrades from previous versions are supported by compiling the releng/15.0 branch. By the way, I only took a moment to search for "releng" in /usr/src/UPDATING, but didn't get a hit. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 104 | Missed a 'the'. Source-based upgrades from previous versions are supported by compiling the releng/15.0 branch. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 104 | With a few minutes of churing on this, I guess something like this was the original intent. Source-based upgrades from previous versions are supported by compiling the releng/15.0 branch. | |
Comment Actions
By the way, I only took a moment to search for "releng" in /usr/src/UPDATING, but didn't get a hit.
Yeah, you wouldn't because UPDATING is branch agnostic. Or rather it's supposed to be up to date and relevant at any point. They're supposed to read the changes at the top since their last update, and then follow the instructions at the bottom.
Comment Actions
Hi pkgbase people! We need good instructions in the "Upgrading from Packages" section of the release note. If you know how to upgrade a pkgbase system to 15.0, help^W now is your time to shine!
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 70–71 | well, there has never been an "official image" of FreeBSD 14 (or earlier) that used pkgbase. 15.0 was the first release that had this. anyone using pkgbase on 14 is using an unreleased, experimental feature entirely at their own risk, and hopefully understood that at the time. i'm not opposed to documenting the upgrade process if someone wants to, but i also don't think it's a huge issue if we don't bother. maybe an informal note on the wiki would be sufficient. the only reason we have this section at all is for people upgrading from 15.0 prereleases, because we do support that and people (correctly) expect it to work. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 98 | Append, do not overwrite. From https://github.com/freebsd/freebsd-doc/commit/7743f2e569d21434ea4041f0857f9134e36fbbb2#r171837919:
| |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 84 | Then, remove two superfluous files? From my major upgrade rough notes: rm /usr/share/keys/pkgbase-15/Makefile rm /usr/share/keys/pkgbase-15/trusted/Makefile | |
| 90 | Maybe make clear that this should not be performed for a major upgrade. Add something to the red alert at https://github.com/freebsd/freebsd-doc/blob/481fce462dc6520dfe29432d673766137b7cd0fc/website/content/en/releases/15.0R/relnotes.adoc?plain=1#L70-L73 (currently the second of the two red alerts at https://www.freebsd.org/releases/15.0R/relnotes/#upgrade-rc). https://forums.freebsd.org/posts/729870 (solved) shows FreeBSD-pkg-bootstrap-15.0.pkg added to FreeBSD 14.3, with no forewarning that it breaks pkg, e.g. root@pkg-issue-2414:~ # pkg bootstrap -f ld-elf.so.1: Shared object "libcrypto.so.35" not found, required by "pkg" root@pkg-issue-2414:~ # | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 81–85 | Please, don't assume that readers will know that /bin/sh must be used. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 81–85 | Sorry, ignore that. I was confused by the ? at the beginning of a command line. | |
Comment Actions
@ziaee thanks for the work on this, and everybody's comments. I think we are best committing this today
because its definitely better than what we currently have, and we can improve on that again as needed.
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 98 | I'm OK for adding another warning for this. But we cannot make release notes work for all combinations All of the user issues identified are really painful for At some point we have to accept that users who are :
Are not on a supported configuration, and are able to I would like this all to be simpler, and better documented, but RN are not the place to fix this. This is what 14.3-RELEASE ships with: FreeBSD: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/quarterly",
mirror_type: "srv",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
enabled: yes
}
FreeBSD-kmods: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/kmods_quarterly_${VERSION_MINOR}",
mirror_type: "srv",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
enabled: yes
}To get into this situation requires several deliberate | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 98 | agreed that running pkgbase on 14.3 is not supported and we don't really need to cover this. however, i'm fairly sure running latest ports *is* a supported configuration (otherwise why would we build those ports?), is a very common thing to do (because of issues with quarterly not getting security fixes, etc.), and does need to be handled in the release notes. but in this case i think the issue is less whether it's supported or not, and more that we shouldn't provide a command using > that unconditionally overrides the user's configuration. either it should use >>, or it should explicitly mention that this should be merged with the existing contents of that file. | |
| website/content/en/releases/15.0R/relnotes.adoc | ||
|---|---|---|
| 98 | https://github.com/freebsd/freebsd-src/pull/1925 leans towards >> within the comments for three usr.sbin/pkg/FreeBSD.conf.* files. | |
Comment Actions
The goal of this commit is to improve the structure. I needed to do it three weeks ago, I'm going to put this in now, with the hope there will be further work upon the additional content we discussed.