# Heads-Up: Deprecation of mergemaster



## zirias@ (Apr 3, 2021)

So far, I was using mergemaster(8) when upgrading from source; it worked fine, and it's also described in the handbook.

Now I learned it's deprecated and will be removed soon. It might be dangerous after 13.0-RELEASE, because it relies on SVN source tags that don't exist any more with git!

For details, see PR 252417.

The recommended tool is etcupdate(8).

I immediately ran into a problem with that, trying to "bootstrap" it with `etcupdate extract`. The reason was: it doesn't play nice with /usr/obj mounted _read-only_. But this is probably not uncommon if you build FreeBSD on one machine and install it on several others that mount /usr/src and /usr/obj via NFS.

The solution is: for each build you do on your building machine, also build a tarball for etcupdate(8) like this:
`etcupdate build -B /usr/obj/etcupdate.tar.bz2`.

This tarball can then be used on any other machine, e.g. for "bootstrapping":
`etcupdate extract -t /usr/obj/etcupdate.tar.bz2`.


----------



## jb_fvwm2 (Apr 3, 2021)

Will someone do a writeup with screenshots so a novice user of etcupdate won't, for example, be locked out from an unwanted change in the password files during an installworld?


----------



## zirias@ (Apr 3, 2021)

Screenshots? Does something like this exist for mergemaster(8)?   

But FWIW, it seems to be updated in the handbook: https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld
Problem is, Google always finds an outdated version…


----------



## PMc (Apr 3, 2021)

Zirias said:


> So far, I was using mergemaster(8) when upgrading from source; it worked fine, and it's also described in the handbook.
> 
> Now I learned it's deprecated and will be removed soon. It might be dangerous after 13.0-RELEASE, because it relies on SVN source tags that don't exist any more with git!


That is strange. Up to Rel. 14 clearly requires to use mergemaster:


```
$ git branch --show-current
main
$ cat UPDATING
[...]
        To rebuild everything and install it on the current system.
        -----------------------------------------------------------
        # Note: sometimes if you are running current you gotta do more than
        # is listed here if you are upgrading from a really old current.

        <make sure you have good level 0 dumps>
        make buildworld
        make buildkernel KERNCONF=YOUR_KERNEL_HERE
        make installkernel KERNCONF=YOUR_KERNEL_HERE
                                                        [1]
        <reboot in single user>                         [3]
        mergemaster -Fp                                 [5]
        make installworld
        mergemaster -Fi                                 [4]
        make delete-old                                 [6]
        <reboot>
```
P.S: Got it: there is a bug-report and it is not closed yet - the docs also will (have to) change at some point in the future...
Probably no need to hurry, as somebody knowledgable of the new tool will hopefully provide drop-in replacements for the procedures in UPDTING.


----------



## zirias@ (Apr 3, 2021)

PMc said:


> That is strange. Rel. 14 clearly requires to use mergemaster:


Probably worth a PR then. See PR in my first posting, and also mergemaster's manpage, it _does_ rely on these source tags, so bad things will happen when using it _after_ the first upgrade to 13 or newer.


----------



## PMc (Apr 3, 2021)

Zirias said:


> Probably worth a PR then. See PR in my first posting


It is already in that PR - there is a grep output and it lists UPDATING.


----------



## dvl@ (Jun 9, 2021)

Zirias said:


> The reason was: it doesn't play nice with /usr/obj mounted _read-only_. But this is probably not uncommon if you build FreeBSD on one machine and install it on several others that mount /usr/src and /usr/obj via NFS.


This is common and I've been using this feature for over 20 years. It is not an edge-case by any means.


----------



## zirias@ (Jun 9, 2021)

dvl@ said:


> This is common and I've been using this feature for over 20 years. It is not an edge-case by any means.


Well, maybe etcupdate should better support this scenario then?  Still, the "workaround" I described in my posting is fine for me!


----------



## Alain De Vos (Jun 9, 2021)

You can run also "etcupdate -p" and i have totally no idea when i should put the "-p" flag or not.

```
-p                 Enable “pre-world” mode.  Only merge changes to files
                        that are necessary to successfully run ‘make
                        installworld’ or ‘make installkernel’.  When this flag
                        is enabled, the existing “current” and “previous”
                        trees are left alone.  Instead, a temporary tree is
                        populated with the necessary files.  This temporary
                        tree is compared against the “current” tree.  This
                        allows a normal update to be run after ‘make
                        installworld’ has completed.  Any conflicts generated
                        during a “pre-world” update should be resolved by a
                        “pre-world” resolve.
```
This is clear. But what does it mean in practice?. When do you use it or not ?


----------



## zirias@ (Jun 9, 2021)

Alain De Vos said:


> This is clear. But what does it mean in practice?. When do you use it or not ?


For me, this is just guesswork: There _might_ be situations where an update to something in /etc is required to successfully execute any `install` target. At least, that's what I interpret there. I've been following FreeBSD since 11 (back when it was -CURRENT) now and never had such a situation. 

*edit:* the handbook tells how it's meant to be used.


----------



## dvl@ (Jun 9, 2021)

Zirias we are trying to duplicate your steps here, on a 12.2 host, upgrading to 13.0

There are 11 steps listed in Updating FreeBSD from Source


After which step do you do `etcupdate extract -t /usr/obj/etcupdate.tar.bz2`?
What steps, if any, does this replace?


----------



## zirias@ (Jun 9, 2021)

dvl@ I can't directly answer to your questions as I was just trying to "bootstrap" `etcupdate`, because I used `mergemaster` before. The situation was having `releng/13.0` in /usr/src and a build of it in /usr/obj, both mounted read-only via NFS. This build was already installed to the target machine (with `installkernel` and `installworld`) and running, /etc was updated one last time with `mergemaster`. Then, executing just `etcupdate extract` failed, IIRC because this tried to write something to /usr/obj.


----------



## dvl@ (Jun 9, 2021)

To be clear, you are doing the bootstrap on 12.2 src and obj?


----------



## zirias@ (Jun 9, 2021)

dvl@ said:


> To be clear, you are doing the bootstrap on 12.2 src and obj?


Nope, that was an error in the first version of the post, I quickly fixed it. I tried it on 13.0. Updating /etc from 12.2 to 13.0 was still done with `mergemaster` before.

I'm not entirely sure the bootstrapping problem was `etcupdate`'s fault, I didn't further analyze it. Since 13.0, I have similar problems with r/o /usr/obj from time to time, with `make installworld` stopping with an error trying to write something to /usr/obj, IIRC in the context of (lib)magic… Repeating `make buildworld` on the building host fixes it.


----------



## dvl@ (Jun 9, 2021)

Zirias said:


> Updating /etc from 12.2 to 13.0 was still done with `mergemaster` before.


This is ambiguous to me and I do not know how to interpret that.


----------



## zirias@ (Jun 9, 2021)

dvl@ said:


> This is ambiguous to me and I do not know how to interpret that.


Uhm. Steps to reproduce (or, maybe not, cause I didn't try to reproduce it myself):

Checkout `releng/13.0` on a build machine running 12.2
Build it (`make buildworld; make buildkernel`)
Mount /usr/src and /usr/obj via NFS r/o on a target machine, also running 12.2
Install 13.0 there (`make installkernel; shutdown -r now; make installworld`)
Update /etc on the target machine with `mergemaster`
Try to bootstrap etcupdate there with `etcupdate extract`


----------



## scottro (Jun 9, 2021)

Does /etc/update give the same presentation of a file? For example, mergemaster shows original on left and new one on right and you hit l or r to get it to work. (And I just tried to find out where I learned that, doesn't seem to be in the man page. Oh well, probably web searched it somewhere.

While, as Zirias says, screen shots might be an odd way to do it, some basic examples of its usage ought to be somewhere.   These days, I only use freebsd-update, so it's not been an issue for me, but it would be nice to have a more detailed explanation


----------



## dvl@ (Jun 9, 2021)

BTW, I think you're doing it wrong based on this extract from the PR

"If you have done several worlds with 'mergemaster' instead, then etcupdate's database in /var/db/etcupdate is stale.  You can overwrite the database by doing 'etcupdate extract' _before_ you do an 'svn up' or 'git pull'.  To check to see what local diffs etcupdate thinks you have, run 'etcupdate diff' (it outputs a patch)."

To me, that says the bootstrap must be done against the src you are upgrading, not the src of what you are upgrading to. In my case, that would be the 12.2 src.

We're going to test this now.


----------



## dvl@ (Jun 9, 2021)

scottro said:


> Does /etc/update give the same presentation of a file? For example, mergemaster shows original on left and new one on right and you hit l or r to get it to work. (And I just tried to find out where I learned that, doesn't seem to be in the man page. Oh well, probably web searched it somewhere.


No, you don't go through that process at all, from what I've seen, but we haven't gotten to that step yet. From the PR:

"If the changes conflict, it saves a version with conflict markers for the user to manually resolve.  At the end of 'etcupdate', it lists any conflicts you manually need to resolve.  For those, you run 'etcupdate resolve' which gives you options to either keep your version, install the new version only, or invoke an editor to resolve the changes."


----------



## zirias@ (Jun 9, 2021)

dvl@ said:


> BTW, I think you're doing it wrong based on this extract from the PR


Not really, my attempt to do `etcupdate extract` was _in preparation_ of the _next_ upgrade (to 13.1). I still used `mergemaster` for the upgrade from 12.2 to 13.0. I understand it won't work reliably any more _after_ that.


----------



## zirias@ (Jun 9, 2021)

dvl@ said:


> No, you don't go through that process at all, from what I've seen, but we haven't gotten to that step yet. From the PR:
> 
> "If the changes conflict, it saves a version with conflict markers for the user to manually resolve.  At the end of 'etcupdate', it lists any conflicts you manually need to resolve.  For those, you run 'etcupdate resolve' which gives you options to either keep your version, install the new version only, or invoke an editor to resolve the changes."


I'm not sure everyone will like that immediately, but for me, having to resolve conflicts "on the go" was always a hassle. I prefer this new approach with conflict markers.


----------



## Terry_Kennedy (Jun 10, 2021)

This may be an unpopular opinion, but I _really_ wish that "STABLE" meant that as well as the ABI / KBI not changing, the tools needed to maintain a system from source also did not change during the life of a major release. I realize that this is an issue that affects comparatively few people - most users either track binaries with freebsd-update(8) or just install a release and don't change anything afterwards, but for those people it does affect, the confusion and effort seems way out of line with the hoped-for benefit.

For example, the PR states:


			
				PR 252417 said:
			
		

> mergemaster(8) has been deprecated for several releases and its replacement--etcupdate(8)--has been present in production systems since at least 9.x/10.x.


So, it missed being officially introduced / changed / documented in 11.x, 12.x, and presumably 13.x but now there's a push to (potentially) introduce a major change to 3 production releases? I just checked the 11.4, 12.2 and 13.0 release notes and it isn't mentioned in any of them.

There has always been a fair amount of this going on in FreeBSD. As a recent example, the ports tree changed from svn to git (also not mentioned in the release notes for 11.4, 12.2 or 13.0) with the last entry in /usr/ports/UPDATING essentially saying "Moved, left no forwarding address" with users having to trawl through the forum and mailing lists to find out what the replacement was, only to find the answer was "Nope, not ready yet. Fixed soon, hopefully.", along with a variety of different unofficial solutions. I don't think that the conversion procedure has been officially described anywhere - I just checked the FreeBSD handbook (PDF edition of 1/23/2021, from the official freebsd.org link). That is far from the only case.

This isn't an argument against change - it is an argument against _unannounced_ change when work has been going on "behind the scenes" but that doesn't get communicated to users until it is presented as a fait accompli. If the replacement of mergemaster(8) wirh etc-update(8) has been "in the works" since FreeBSD 10.4 (taking the PR's "since 9.x/10/x" at its latest possible date), it has been over 3.5 years since this decision was made. If one assumes it has been since FreeBSD 10.0, that has been over 7 years. And in the same version of the handbook I mentioned above, there are zero mentions of etcupdate(8). Looking at /usr/src/UPDATING (svn r369959) there are 4 mentions of etcupdate(8), all of which are of the form "mergemaster or etcupdate".

It is a reasonable thing to ask me "If you're so concerned about it, why don't you write up an article and post it to the wiki?" A reasonable question, except that I usually find out about this the same time everybody else it affects does - when the sky falls. Sure, I could write something up, proofread it, ask for some reviews and when everyone is happy, post it to the wiki. But by then most people who care will have likely either figured it out on their own or given up. Not to mention that there would be no pointers to the wiki, which has a bunch of outdated and incomplete articles and thus isn't a particularly trustworthy source of information. As an example (yes, I know my example is ports-related, I'm making a point here), look at the pages for Python3Default (last updated 2020-10-10) and Python2EOL (last updated 2021-04-25), neither of which has any information useful to end users. The first article is downright misleading for developers (there is lots of out-of-date information there) and the sole nugget of useful information for developers in the second article can be summed up as "Please use USES=python:3.6+ from now on".


----------



## bakul (Jun 10, 2021)

Terry_Kennedy said:


> It is a reasonable thing to ask me "If you're so concerned about it, why don't you write up an article and post it to the wiki?" A reasonable question, except that I usually find out about this the same time everybody else it affects does - when the sky falls.


If the core group (or some review group) does a weekly/biweekly/monthly review of commits for the purpose of preparing release notes, that can also provide an early warning system. I think by the time release notes come out, it is too late; changes have been baked in. And warning what features might get deprecated in the next release may be too early as people keep using what works for them until all of a sudden it doesn’t.


----------



## Terry_Kennedy (Jun 10, 2021)

bakul said:


> If the core group (or some review group) does a weekly/biweekly/monthly review of commits for the purpose of preparing release notes, that can also provide an early warning system. I think by the time release notes come out, it is too late; changes have been baked in. And warning what features might get deprecated in the next release may be too early as people keep using what works for them until all of a sudden it doesn’t.


I'm pretty sure that Bugzilla has a "Relnotes: Y/N" flag. If it wasn't Bugzilla, it was Phabricator.

If there's a heads-up in the release notes for a release where the old way still works, that'd be great. I'd be happy with it showing up in the release notes for the next major version where it takes effect. People who don't read the release notes before upgrading to a new major release are likely to encounter other surprises along the way. Not that I said "major release" - I don't think low-urgency changes like this are appropriate to happen in a point release - in this case, if it waited 3.5 years it can wait a while longer.

Committing a change to mergemaster(8) (in this case) saying "This utility will be deprecated in FreeBSD 14.0 - refer to https://www.freebsd.org/someURL for more information" with a pause (similar to the way portupgrade(1) warns about an unsupported FreeBSD version) would be great, too - once the timeframe and target release are known.


----------



## zirias@ (Jun 10, 2021)

Terry_Kennedy said:


> Not that I said "major release" - I don't think low-urgency changes like this are appropriate to happen in a point release


There's no way to keep mergemaster(8) working, it relies on source tags GIT just won't generate.

Also note PR 252417 starts like this:


> mergemaster(8) has been deprecated for several releases and its replacement--etcupdate(8)--has been present in production systems since at least 9.x/10.x.



So, there probably _was_ a deprecation notice. Maybe many didn't read it. Also, the handbook used etcupdate(8) for a while, but there's been this ongoing problem of finding an old and outdated version of the handbook with Google…


----------



## Terry_Kennedy (Jun 10, 2021)

Zirias said:


> There's no way to keep mergemaster(8) working, it relies on source tags GIT just won't generate.


I believe there was agreement to continue to provide svn updates through the life of 12.x.


Zirias said:


> Also note PR 252417 starts like this:


Exactly. Some people have known about this for a minimum of 3.5 years (assuming the PR meant 10.4). Expecting users to read every bug report to find which happen to mention changes that break existing procedures isn't reasonable. This reminds me of a Douglas Adams quote.


Zirias said:


> So, there probably _was_ a deprecation notice. Maybe many didn't read it. Also, the handbook used etcupdate(8) for a while, but there's been this ongoing problem of finding an old and outdated version of the handbook with Google…


I specifically checked the official master FreeBSD copy of the Handbook from: https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf (no hotlink title so the URL is visible in the post). Word search in Acrobat: etcupdate, 0 matches; mergemaster, 25 matches.

I always do read the release notes and errata, and I don't remember seeing it. That doesn't mean there never was one, of course. Even if there was, this is the sort of thing that should remain in the release notes until the change happens (and then the release notes should say that as of the version the release notes pertain to, things have changed).


----------



## zirias@ (Jun 10, 2021)

Terry_Kennedy said:


> I believe there was agreement to continue to provide svn updates through the life of 12.x.


Yes, 12.x is not affected. Branches for 13.x exist only in GIT though.



Terry_Kennedy said:


> I specifically checked the official master FreeBSD copy of the Handbook from: https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf (no hotlink title so the URL is visible in the post). Word search in Acrobat: etcupdate, 0 matches; mergemaster, 25 matches.


This is the old, outdated content indeed. So you probably discovered a bug here, maybe with building the PDF version…

The HTML version (which is linked in the top menu as well as on top of https://docs.freebsd.org/en/ ) is correct.



Terry_Kennedy said:


> I always do read the release notes and errata, and I don't remember seeing it. That doesn't mean there never was one, of course. Even if there was, this is the sort of thing that should remain in the release notes until the change happens (and then the release notes should say that as of the version the release notes pertain to, things have changed).


You won't repeat a deprecation note in every release. I _think_ doing it once and updating the handbook really is good enough, but the main problem here seems to be too many editions of the handbook with outdated content floating around. The PDF you found really is a bummer. And yes, I was surprised to find mergemaster(8) deprecated as well.


----------



## driesm (Jun 10, 2021)

Alain De Vos said:


> You can run also "etcupdate -p" and i have totally no idea when i should put the "-p" flag or not.
> <snip>
> This is clear. But what does it mean in practice?. When do you use it or not ?



As I rewrote that part of the handbook to use etcupdate over mergemaster I can elaborate a bit more on this. One recent change where `etcupdate -p` was needed was the addition of the system ntpd user. If you would update from source with that commit including, the ntpd user would not be present yet on the running system. This would cause error messages when running `installworld` because it references that user in the install() command to install files as that user, `installworld` would fail saying something like "ntpd user not existing, or UID 123 not existing". Honestly, you can safely run `etcupdate -p` every time you update from source, if it doesn't need to do anything it wont do anything.



PMc said:


> That is strange. Up to Rel. 14 clearly requires to use mergemaster:
> <snip>
> P.S: Got it: there is a bug-report and it is not closed yet - the docs also will (have to) change at some point in the future...
> Probably no need to hurry, as somebody knowledgable of the new tool will hopefully provide drop-in replacements for the procedures in UPDTING.



Changes to /usr/src/UPDATING have been under review for way to long causing confusing.
I have added a reminder so that both the handbook and the instructions shipped with the source are the same.


----------



## Terry_Kennedy (Jun 10, 2021)

Duffyx said:


> Changes to /usr/src/UPDATING have been under review for way to long causing confusing.
> I have added a reminder so that both the handbook and the instructions shipped with the source are the same.


I'm not singling you out here, honest. But the Phabricator review shows the exact problem I'm talking about. If you are coming to FreeBSD via a new install, your instructions are perfect. However, for people who have been using / updating FreeBSD for ages, it is incomplete information in the wrong place. In addition to what you have way at the bottom in "COMMON ITEMS", there should be something like this with the current date, near the top:

```
20210610:
        The default method of updating system configuration files has changed from
        mergemaster to etcupdate. If you have been using mergemaster, please perform
        the following steps to convert to using etcupdate:
          Before updating your source tree, buildworld, installworld, etc:
            1) ...
            2) ...
            3) ...
         After running buildworld, installworld, etc:
            1) ...
            2) ...
        After you have converted to etcupdate, only the second set of steps will be
        needed.
```
While someone is in there, converting from svn to git should also be covered (preferably recommending the lightweight gitup client, similar to the way svnlite is used instead of full svn).

Again, I'd like to _strongly_ suggest that changes like this not happen during the lifetime of a release, but only when a new x.0 is promoted to STABLE. As I am unlikely to win that one, it is even more important that things like this be noted in /usr/src/UPDATING.


----------



## Alain De Vos (Jun 10, 2021)

People always do their effort. This time it is possible to formulate the complexity in a simple way.
Order:
1.Run "etcupdate -p" as pre-installworld etc-update.
2.Run installworld
3.Run "etcupdate" as post-installworld etc-update.

We live in a non-perfect world of non-perfect persons. And my name is non-perfect.
But if things are clarified in timely matter, which they are, I can live with it.
(And mergemaster was ready for improvement.)


----------



## zirias@ (Jun 10, 2021)

Terry_Kennedy said:


> Again, I'd like to _strongly_ suggest that changes like this not happen during the lifetime of a release, but only when a new x.0 is promoted to STABLE. As I am unlikely to win that one, it is even more important that things like this be noted in /usr/src/UPDATING.


Well, in fact, the reason mergemaster(8) won't work reliably any more is directly tied to the switch to GIT, which _was_ made for a new major release. Still being able to use mergemaster(8) for the upgrade from 12.2 to 13.0 is a side effect of how it works and not really intended.

But I guess you _do_ have a point here that communication could have been better. It hit me by surprise as well


----------



## Terry_Kennedy (Jun 10, 2021)

Alain De Vos said:


> People always do their effort. This time it is possible to formulate the complexity in a simple way.
> Order:
> 1.Run "etcupdate -p" as pre-installworld etc-update.
> 2.Run installworld
> ...


From what I've read in this topic and in the PR, it seems to be necessary to "pre-load" etcupdate with "the way things are" if an install has been using mergemaster up to the present time. What you describe appears fine (I've never run it so I can't say for sure) for systems that have always used etcupdate. The issue is "how do we get there from here?" on existing systems that use mergemaster, and communicating that clearly near the top of UPDATING.


----------



## zirias@ (Jun 10, 2021)

Terry_Kennedy said:


> From what I've read in this topic and in the PR, it seems to be necessary to "pre-load" etcupdate with "the way things are" if an install has been using mergemaster up to the present time. What you describe appears fine (I've never run it so I can't say for sure) for systems that have always used etcupdate. The issue is "how do we get there from here?" on existing systems that use mergemaster, and communicating that clearly near the top of UPDATING.


It's by the way the very reason I decided to start this thread. Yes, if you used mergemaster before, you have to bootstrap etcupdate (while installing a binary release will come with a bootstrapped etcupdate) and I wasn't aware before. And it's suprirising how many people weren't aware, even including some committers it seems  (my motivation to start the thread was to increase awareness before people start shooting their feet…)

So I'm with you that there is some problem. But I still don't think deprecating a tool should be mentioned more than once, my guess is that the change to the hanbook might have been too late (not sure about that), _and_ there are too many outdated versions still available. Seeing that the PDF version still doesn't have the relevant change is really bad…

Additionally, yes, an UPDATING entry for RELEASE-13.0 should have been there.


----------



## grahamperrin@ (Jun 10, 2021)

Alain De Vos said:


> … Order:
> 1.Run "etcupdate -p" as pre-installworld etc-update.
> 2.Run installworld
> 3.Run "etcupdate" as post-installworld etc-update.



Early this morning, in the absence of notes, I mistakenly ran things in the *wrong* order: 

`etcupdate -B` _before_ installworld
`make installworld`
`etcupdate -p` _post_ installworld.
After rebooting (and regaining access to notes) I realised my mistake. Things seem to work, touch wood, but should I do anything in particular to put right what I did wrong?

14.0-CURRENT, updated from n247020-e0fa04e257c to n247266-5e5ca4c8fc5.


```
% bectl list -c creation
BE                    Active Mountpoint Space Created
n246499-097e8701c9f-d -      -          11.6G 2021-05-12 16:33
n247020-e0fa04e257c-d -      -          4.33G 2021-06-05 07:53
n247020-e0fa04e257c-e -      -          61.2M 2021-06-06 13:45
n247266-5e5ca4c8fc5-a NR     /          57.3G 2021-06-10 00:43
%
```


----------



## Alain De Vos (Jun 10, 2021)

I can tell what I had done.
Backup of /etc directory
etcupdate extract
cp -axfvR the newly extracted /etc in /var over the existing /etc
Perform manual changes.
This procedure is not for the faint of hart but gave me in my case a "virgin" system.


----------



## Terry_Kennedy (Jun 10, 2021)

Zirias said:


> Well, in fact, the reason mergemaster(8) won't work reliably any more is directly tied to the switch to GIT, which _was_ made for a new major release. Still being able to use mergemaster(8) for the upgrade from 12.2 to 13.0 is a side effect of how it works and not really intended.


With 10.4 being released October 3rd, 2017 and 13.0 being released April 13, 2021 there was still more than 3 years to provide a heads-up, switch 13.0-RELEASE to etcupdate, deal with any questions, and so on. That didn't happen. If it wasn't time-critical enough that it didn't matter whether or not it made it into 13.0 after 3 years, then it should wait until 14.0. If that isn't possible due to the tags that mergemaster depends on "going away" in 13, then the way in which it was decided to proceed with the changeover to git for 13 should be looked at, to discover why an important piece of infrastructure (mergemaster / etcupdate) was not considered.

We had similar things happen with the conversion from CVS to Subversion. That time the justification was that there may have been a compromise in one of the CVS repositories. Of course, a number of us felt at the time that it was a "the dog ate my homework" excuse.


----------



## zirias@ (Jun 10, 2021)

There's still time to fix this. For users of -RELEASE versions, nothing will go wrong with mergemaster(8) up until now. Things would start to go wrong when updating to 13.1. Users of development branches are (rightfully) expected to follow mailing lists etc to know things they need to know.

So, the course of action now should be:

Make sure every published edition of the handbook is up-to-date, _delete_ outdated content (people use Google)
Add something to UPDATING for former users of mergemaster(8) to guide them
It _should_ have happened before 13.0-RELEASE, sure, but you can't fix that now, and it doesn't help to get furious about that…


----------



## Alain De Vos (Jun 10, 2021)

We need also a part "how to 'bootstrap' etcupdate" for the first time.


----------



## Terry_Kennedy (Jun 10, 2021)

Zirias said:


> There's still time to fix this. For users of -RELEASE versions, nothing will go wrong with mergemaster(8) up until now. Things would start to go wrong when updating to 13.1. Users of development branches are (rightfully) expected to follow mailing lists etc to know things they need to know.
> 
> So, the course of action now should be:
> 
> ...


And add a warning message to mergemaster saying that is is being deprecated, with a link to some place it is documented.


Zirias said:


> It _should_ have happened before 13.0-RELEASE, sure, but you can't fix that now, and it doesn't help to get furious about that…


I'm not furious, just disheartened that the Project keeps shooting itself in the foot over and over again. With collateral damage to other feet that happen to be standing nearby.


----------



## zirias@ (Jun 10, 2021)

Terry_Kennedy said:


> And add a warning message to mergemaster saying that is is being deprecated, with a link to some place it is documented.


That's a great idea, and again, _should_ have been done much earlier… 



Terry_Kennedy said:


> I'm not furious, just disheartened that the Project keeps shooting itself in the foot over and over again. With collateral damage to other feet that happen to be standing nearby.


Just keep things in perspective. FreeBSD is still an open-source project with a lot of people working on it in their spare time. Sure that's not an excuse for failing, but often an explanation. If you compare to other FOSS projects, FreeBSD doesn't do bad, the overall documentation quality is great (IMHO).

So what to do with that? At the best, learn a lesson, somehow…


----------



## Terry_Kennedy (Jun 11, 2021)

Zirias said:


> Just keep things in perspective. FreeBSD is still an open-source project with a lot of people working on it in their spare time. Sure that's not an excuse for failing, but often an explanation. If you compare to other FOSS projects, FreeBSD doesn't do bad, the overall documentation quality is great (IMHO).


Lots of developers work on things that they enjoy. Some developers work on things their employers pay them to do. And some developers dig through the PRs and other stuff that nobody really wants to look at, because it needs to be done. That last one is a thankless job, but may very well be the most important of the bunch.

It is _because_ we have such talented developers in all 3 categories that I don't understand why stuff like this drops through the cracks. For example, if code goes through a Phabricator review and (for example) "docs" gets added as a reviewer, it seems to me that some time in the last 3.5 years this could have progressed to being more complete than the state it currently is in.



Zirias said:


> So what to do with that? At the best, learn a lesson, somehow…


Agreed. The problem with repeatedly shooting yourself in the foot is that you eventually run out of feet, though.


----------



## grahamperrin@ (Jun 11, 2021)

grahamperrin said:


> to put right what I did wrong?



Answered in Discord. `etcupdate -B`


----------



## scottro (Jun 11, 2021)

I just tried a source update on a test machine, and found that etcupdate worked without problem. I followed the handbook's instructions of running etcupdate -p and, after installing world, etcupdate -B.  This seemed to correctly update /etc files. For example, with mergemaster, I would have to manually merge /etc/passwd, but etcupdate did it correctly without manual intervention.  (This is a simple install, a single disk, using ZFS).


----------



## dvl@ (Jun 11, 2021)

We've managed to upgrade two hosts from 12.2 to 13.0:


one required a `etcupdate` bootstrap because it has been updated numerous times using `mergemaster`
the second was originally installed as 12.2 and did not require this bootstrap
I hope  to have a blog post outlining the steps soon. We have some follow-up issues on the second host and we will work on resolving those today.


----------



## jb_fvwm2 (Jun 24, 2021)

`etcupdate extract; etcupdate diff | less; /usr/src/usr.sbin/mergemaster.sh -viPpc ...` and there remains with`etcupdate diff` a whole lot of files I am hesitant to do any further operations
on with `etcupdate resolve` because of their `svn`
alike 'tc' terse all-or-none 3-way rather than the PLAIN left side, right side
usage of `mergemaster` :
[ and am thus worried about an impending installworld... , BESIDES the
usual sometimes-failing-midway of the installworld ]
5 files in root: /root/.shrc 
aliases , sysctl.conf, groups, ttys,  and about 20 others
I or the system had revised over the past 17 years or so.
...............
I hope to update this post with good news in  a few days [ v 12.2 stable to
v 13 stable. ]


----------



## dvl@ (Jun 24, 2021)

dvl@ said:


> We've managed to upgrade two hosts from 12.2 to 13.0:
> 
> 
> one required a `etcupdate` bootstrap because it has been updated numerous times using `mergemaster`
> ...


Of note:

Our build process involves `buildkernel` and `buildworld` on one of our faster hosts (i.e. the build host). We built 13.0 on a 12.2 host. This is standard procedure. Nothing unusual. The results are then available via NFS mounts for other [slower] hosts.

The first host upgraded from 12.2 to 13.0 was successful after a few failed attempts. We did the `etcupdate` bootstrap on the first update.  Details of how and why this is required for SOME hosts is in this comment of the PR mentioned by OP.

The next host to be updated was the build host. This upgrade from 12.2 to 13.0 was successful on the first try.

All the 13.0 hosts were having trouble with Kerberos. We eventually identified a problem with "ugidfw starts before late mount of nfs causing permissions errors on /var/run/nslcd" (see PR 256658). Once we identified the solution, we amended ugidfw on our 13.x sources, and rebuilt world.

This change broke upgrades.


```
# make -j4 installkernel
--- installkernel ---
--- _installcheck_kernel ---
--------------------------------------------------------------
>>> Install check kernel
--------------------------------------------------------------
--- installkernel ---
--------------------------------------------------------------
>>> Installing kernel GENERIC on Wed Jun 23 13:17:16 EDT 2021
--------------------------------------------------------------
cd /usr/obj/usr/src/amd64.amd64/sys/GENERIC;  MACHINE_ARCH=amd64  MACHINE=amd64  CPUTYPE= CC="cc -target x86_64-unknown-freebsd13.0 --sysroot=/usr/obj/usr/src/amd64.amd64/tmp -B/usr/obj/usr/src/amd64.amd64/tmp/usr/bin" CXX="c++  -target x86_64-unknown-freebsd13.0 --sysroot=/usr/obj/usr/src/amd64.amd64/tmp -B/usr/obj/usr/src/amd64.amd64/tmp/usr/bin"  CPP="cpp -target x86_64-unknown-freebsd13.0 --sysroot=/usr/obj/usr/src/amd64.amd64/tmp -B/usr/obj/usr/src/amd64.amd64/tmp/usr/bin"  AS="as" AR="ar" LD="ld" LLVM_LINK=""  NM=nm OBJCOPY="objcopy"  RANLIB=ranlib STRINGS=  SIZE="size" STRIPBIN="strip" PATH=/usr/obj/usr/src/amd64.amd64/tmp/bin:/usr/obj/usr/src/amd64.amd64/tmp/usr/sbin:/usr/obj/usr/src/amd64.amd64/tmp/usr/bin:/usr/obj/usr/src/amd64.amd64/tmp/legacy/usr/sbin:/usr/obj/usr/src/amd64.amd64/tmp/legacy/usr/bin:/usr/obj/usr/src/amd64.amd64/tmp/legacy/bin:/usr/obj/usr/src/amd64.amd64/tmp/legacy/usr/libexec::/sbin:/bin:/usr/sbin:/usr/bin  make  KERNEL=kernel install
make[2] warning: /usr/obj/usr/src/amd64.amd64/sys/GENERIC: Read-only file system.
ld-elf.so.1: /usr/obj/usr/src/amd64.amd64/tmp/legacy/usr/sbin/make: Undefined symbol "regcomp@FBSD_1.6"
*** [installkernel] Error code 1

make[1]: stopped in /usr/src
1 error

make[1]: stopped in /usr/src
```

Why? Why is it trying to write to /usr/obj?

The answer came from PR 253727 - You cannot upgrade a 12.2 host using a build from a 13.0 host.  The build must be done on a 12.x host.  We will be creating a 12.2 jail on our 13.x host and redo our `buildkernel` and `buildworld`.


----------



## Alain De Vos (Jun 24, 2021)

Design for the build environment for FreeBSD: no support of newer building to run on older. Seems legit.


----------



## dvl@ (Jun 24, 2021)

Alain De Vos said:


> Design for the build environment for FreeBSD: no support of newer building to run on older. Seems legit.


Yes, it does. However, it is something easily overlooked and missed when concentrating on the bigger issues. It is something to keep in mind. I always mention issues I encounter because if they stump an experienced person, they will surely hit others.


----------



## Alain De Vos (Jun 24, 2021)

No rocket science, to prevent upgrade surprises, I've made a list of the files i've touched,

```
devfs.conf -> /etc/devfs.conf
devfs.rules -> /etc/devfs.rules
FreeBSD.conf -> /usr/local/etc/pkg/repos/FreeBSD.conf
fstab -> /etc/fstab
group -> /etc/group
hostid -> /etc/hostid
hosts -> /etc/hosts
ipfw.rules -> /etc/ipfw.rules
jail.conf -> /etc/jail.conf
localtime -> /etc/localtime
login.conf -> /etc/login.conf
make.conf -> /etc/make.conf
newsyslog.conf -> /etc/newsyslog.conf
nsswitch.conf -> /etc/nsswitch.conf
passwd -> /etc/passwd
periodic.conf -> /etc/periodic.conf
rc.conf -> /etc/rc.conf
rc.local -> /etc/rc.local
resolv.conf -> /etc/resolv.conf
resolvconf.conf -> /etc/resolvconf.conf
shells -> /etc/shells
src-env.conf -> /etc/src-env.conf
src.conf -> /etc/src.conf
sysctl.conf -> /etc/sysctl.conf
ttys -> /etc/ttys
```


----------



## zirias@ (Jun 24, 2021)

dvl@ said:


> Yes, it does. However, it is something easily overlooked and missed when concentrating on the bigger issues. It is something to keep in mind. I always mention issues I encounter because if they stump an experienced person, they will surely hit others.


Just confirming I ran into the same thing, following -RC versions on a few machines, and then trying to update one to 13.0-RELEASE that was still on 12.2. Once it happened, it didn't take much time thinking about it to realize what went wrong ("bootstrapping" tools built and linked for 13.0...) – but quite some time to "fix" it, setting up a 12.2 jail and building world again. A lesson learned


----------



## astyle (Jun 24, 2021)

Terry_Kennedy said:


> And some developers dig through the PRs and other stuff that nobody really wants to look at, because it needs to be done. That last one is a thankless job, but may very well be the most important of the bunch


I completely agree with that... shiny new stuff works best when you have a solid foundation underneath, and not a house of cards... Sometimes, nobody wants to look at the foundational stuff because nobody can understand it that well, and the only dev who does have a decent handle on the foundational stuff is no longer involved.


----------



## Terry_Kennedy (Jun 24, 2021)

astyle said:


> Sometimes, nobody wants to look at the foundational stuff because nobody can understand it that well, and the only dev who does have a decent handle on the foundational stuff is no longer involved.


I'm reminded of my departed friend dmr's famous "You are not expected to understand this" comment in Sixth Edition. Similar arcane magic still lives in the lower levels of the code, I'm sure.

Side anecdote: The linked article by dmr also contains the explanation for the [in]famous "values of β will give rise to dom!" `mv` error message. dmr actually collected those sorts of "strange messages found on output devices" things. When I was doing the output driver for the Linotron 202 phototypesetter, lots of gibberish would come out because the software that ran on the "Naked Mini" that ran the 202 was buggy, and my code had all sorts of workarounds for "don't give this command because it will crash the 202" things. Despite all of that, the 202 would occasionally go b*tsh!t crazy (that's a technical term) and typeset gibberish on a whole film cassette. This would consist of random pieces of user commands, contents of the 202's memory, and whatever else was within reach. One day the 202 generated (in the middle of the gibberish) around 2 inches of leading, "font le oops", and another 2 inches of leading. "font" was was rendered in normal Times Roman, but "le oops" was one character from each of many different fonts, in a variety of font sizes, like a ransom note. I gave it to dmr for his collection.

Side anecdote to a side anecdote: I'm the person that came up with the 4-character hexadecimal display on top of the 202. On the original units, if the 202 hit an error it would display an error on 16 LEDs on a card in the processor chassis. But you had to open the door to look at the code, then convert the 16 LEDs to hex and look it up in the book. And of course, to open the door you had to remove the film cartridge - a total PITA. So I scavenged 4 of the HP 5082 hex decoder / display units and stuck them in a Radio Shack 270-285 project case, normally used for clocks. The whole thing sat on top of the 202, above the operator control panel. Since the LED signals weren't brought out anywhere useful like the backplane, I ran a white wire-wrap wire from each LED and a ground wire to a DB-25 connector that dangled from the front of the card. A regular round multi-conductor cable brought those signals up to the display. I was quite surprised to see a 202 some years later, after I'd left the typesetiing industry, with one of those boxes. But not built by me! Apparently someone thought it was a good idea and started selling them. I just did them for our in-house 202s.

We now return you to your regularly scheduled programming (discussion) 

_Edited to fix broken link_


----------



## Alain De Vos (Jun 25, 2021)

There is something with sendmail I don't know what. Historicly it's part of base, but when upgrading creates problems one should look to put it in ports. Where it belong according to my personal opinion.


----------



## Terry_Kennedy (Jun 25, 2021)

Alain De Vos said:


> There is something with sendmail I don't know what. Historicly it's part of base, but when upgrading creates problems one should look to put it in ports. Where it belong according to my personal opinion.


It has been discussed for quite some time now. Moving things out of base has been going on for a while. One big example is BIND (which, IMHO, is another one of those "_THAT_ could have gone better" things - the port didn't support chrooted BIND for quite a while after it got kicked out of base).

The issue is figuring out a lightweight replacement MTA/MUA that is acceptable to just about everybody. I think that is where it has hit snags in the past.

Having said all that, I can't remember a time I've had a problem with sendmail during an upgrade. But I do specify a site-specific configuration file in /etc/make.conf:
	
	



```
SENDMAIL_MC=/usr/local/src/sendmail/freebsd-with-ciphers.mc
```
If you run into issues when upgrading, you should file a PR on it. After all, it is in base.


----------



## grahamperrin@ (Jun 25, 2021)

Terry_Kennedy said:


> "le oops"



I want to steal this. Instead, I'll just think of it, and your anecdotes, whenever appropriate. Thank you.


----------



## Alain De Vos (Jun 25, 2021)

You don't need a replacement for sendmail in base. Let the installer give you a few package options , not in base, as MTU. That is according to me the way to go.
It means you break a historical link, but the world moves forward.
Sendmail is certainly not dead, but newer, better alternatives exist for smaller system, like the ones for a home PC or a desktop.

In run opensmtpd thanks to openbsd.
Here i post my configuration file,

```
pki mail.ala cert "/etc/ssl/opensmtpd_public.pem"
pki mail.ala key  "/etc/ssl/opensmtpd_private.pem"
table aliases file:/etc/mail/aliases
listen on mail.ala
action "local" maildir "~/Maildir" alias <aliases>
action "relay" relay
match for local action "local"
match from local for any action "relay"
```
That's it. Nothing more.
There is more opensmtpd compiles in less then one minute.
This is 60*24 times faster then chromium-browser


----------



## Terry_Kennedy (Jun 25, 2021)

Alain De Vos said:


> You don't need a replacement for sendmail in base. Let the installer give you a few package options , not in base, as MTU. That is according to me the way to go.
> It means you break a historical link, but the world moves forward.
> Sendmail is certainly not dead, but newer, better alternatives exist for smaller system, like the ones for a home PC or a desktop.


Well, this is something that could be handled by PkgBase. Which is hopefully something that won't introduce changes for the "always build world + kernel from source" users like me.


----------



## Alain De Vos (Jun 25, 2021)

Another thing would be the kernel as a package or the loader as package. But who dares ?


----------



## grahamperrin@ (Jun 25, 2021)

Alain De Vos said:


> … who dares ?



GhostBSD  <https://github.com/ghostbsd/ghostbsd-ports/tree/main/os>


----------



## astyle (Jun 25, 2021)

Alain De Vos said:


> You don't need a replacement for sendmail in base. Let the installer give you a few package options , not in base, as MTU. That is according to me the way to go.
> It means you break a historical link, but the world moves forward.
> Sendmail is certainly not dead, but newer, better alternatives exist for smaller system, like the ones for a home PC or a desktop.
> 
> ...


Sorry, but sendmail is different than SMTPd... I would know, I set both up on FreeBSD 6.0 for a small shop when I was fresh out of college. /bin/sendmail is the thing that sends and receives IP packets out on port 25. SMTPd is the service that tells sendmail to receive and send those packets. IMAPd is what sits between sendmail and a user's email client, be it Outlook, Thunderbird, or a web interface like gmail. I had to line everything up, and work out a way to switch things back if that didn't work. All that prep had to be complete before spending about half an hour flipping the switch.

Unfortunately, we're getting off topic...


----------



## Alain De Vos (Jun 25, 2021)

opensmtpd. It has evolved. 

```
sockstat -46 | grep 25
_smtpd   smtpd      34582 9  tcp4   127.0.0.1:25          *:*
```


----------



## Alain De Vos (Jun 25, 2021)

grahamperrin said:


> GhostBSD  <https://github.com/ghostbsd/ghostbsd-ports/tree/main/os>


The subdirectories of /usr/src are,

```
bin/
cddl/
contrib/
crypto/
etc/
gnu/
include/
kerberos5/
lib/
libexec/
release/
rescue/
sbin/
secure/
share/
stand/
sys/
targets/
tests/
tools/
usr.bin/
usr.sbin/
```
According to me , with even my little C-language knowledge there is room for improvement.
But that is for the commiters. And i don't think they spend time on fora.
Maybe there is so much code people do not dare to touch.
And if you touch you convince other persons which is everything except simple.


----------



## Terry_Kennedy (Jun 25, 2021)

Terry_Kennedy said:


> I specifically checked the official master FreeBSD copy of the Handbook from: https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf (no hotlink title so the URL is visible in the post). Word search in Acrobat: etcupdate, 0 matches; mergemaster, 25 matches.


I just re-checked that URL and it still has the old version of the Handbook. In fact, that seems to be the case for every format of every language of the Handbook. So I attempted to send the attached to freebsd-doc@, as recommended in the Handbook itself:

```
In https://tinyurl.com/45wtwnby (and surrounding replies) I noted that
the official PDF version of the FreeBSD Handbook from:
https://download.freebsd.org/ftp/doc/en/books/handbook/book.pdf
is the version from January 23, 2001. Of relevance to that particular
forum discussion, the PDF version of the Handbook still refers to using
mergemaster, while the HTML version of the Handbook uses etcupdate.

  Looking at other various languages (I checked DE, ES and FR) they all
have dates from late January. It appears that whatever system is used to 
re-generate the downloadable Handbook variants has been broken since
late January.

  In addition, while researching this I have discovered 2 other issues
which the Documentation Project might want to address:

  1) The tree that is apparently the "definitive version" of the Handbook
     at https://docs.freebsd.org/en/books/handbook/ does not include any
     date or version information other than a copyright date. That makes
     it impossible to tell what version is being viewed. I suggest that
     the same text that appears in the hardcopy edition, namely:

        FreeBSD Handbook
        Revision: 0d4371e5cc
        2021-01-18 18:33:37 +0100 by Fernando Apesteguma.

     (auto-updated as appropriate) appear in the online edition as well.

  2) Any downloadable / printable versions of the handbook should contain
     something like the following text:

        The FreeBSD Handbook is a living document. By definition, down-
        loaded or printed editions will soon be out-of-date. Please refer
        to https://docs.freebsd.org/en/books/handbook/ (for the online
        edition) or https://download.freebsd.org/ftp/doc/ (for download-
        able editions) to obtain the latest version.

        Thanks for your time,
        Terry Kennedy     http://www.glaver.org      New York, NY USA
```
However, since the migration of lists.freebsd.org from Mailman to Mlmmj, it seems to no longer be possible to send to mailing lists one isn't subscribed to. In the past it used to be possible to "throw a note over the wall" to a list one wasn't subscribed to, after manual moderator review. That no longer seems to be possible (probably an attempt to reduce spam, although I note that the most recent message in the freebsd-doc archive is spam from "Sponsored Ads").

So, if anyone posting here is a member of freebsd-doc@, feel free to pass this along.

In any event, these are things that someone with admin privileges on the web server needs to fix (the lack of updates to the downloadable versions) and that someone with doc commit privileges would need to do (my suggested changes to the online and downloadable versions). So all I can do is mention it here.


----------



## grahamperrin@ (Jun 25, 2021)

Terry_Kennedy said:


> … if anyone posting here is a member of freebsd-doc@, feel free to pass this along. …



I'm probably not a member, instead I linked to your post in *documentation* at <https://discord.com/channels/727023752348434432/760416197803245591/857869918922080276>


----------



## Alain De Vos (Jun 25, 2021)

All this old pdf/html documentation should be trown in the bin. And just leave the current html handbook.


----------



## grahamperrin@ (Jun 25, 2021)

Alain De Vos said:


> All this old pdf/html documentation should be trown in the bin. And just leave the current html handbook.



The HTML handbook lacks the index, lacks a link to the glossary, and so on. A single document, the PDF, is essential for search purposes.


----------



## Alain De Vos (Jun 25, 2021)

True. A cronjob which creates each day a pdf out of the source/html ?


----------



## scottro (Jun 25, 2021)

Just typed freebsd handbook into startpage, and got a link to https://download.freebsd.org/ftp/doc/handbook/book.pdf

Under abstract, it says, 

```
Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD 12.2-RELEASE, FreeBSD 12.1-RELEASE, and FreeBSD 11.4-RELEASE.
```
So, not quite up to date but better than 2001. 

However, one of the main annoyances of the handbook is that if you search online, it's usually not dated. It's worse for 3rd party stuff which changes more, and now, there is the FreeBSD wiki, making it so that you don't always know whether to search the handbook or the wiki, and if you find both, which one is more current, etc.  

I'd disagree with Alain De Vos about it all being thrown out. Just clearly date it, and note which version is being documented. Some people keep old versions and may still have use for old documentation. (Or have a cut off, e.g., throw out 9.x
when 13.x gets released, or something like that.) I still find old stuff from say, freebsddiary.org quite useful.


----------



## Phishfry (Jun 25, 2021)

Alain De Vos said:


> All this old pdf/html documentation should be trown in the bin. And just leave the current html handbook.


Maybe plainly mark it ARCHIVE and keep it for historical reasons..
Somehow we need better way to show what is current. No need to throw out the past.


----------



## Alain De Vos (Jun 25, 2021)

Yes backup old stuff, but only for archeological purposes.
And somehow prevent that it lists up in google searches. Only when you do explicit search.
E.g. zip it.
And move it from place so obsolete or forgotten links become dead links.
This reminds that relative links can be usefull instead of full path links.


----------



## astyle (Jun 25, 2021)

Alain De Vos said:


> Yes backup old stuff, but only for archeological purposes.
> And somehow prevent that it lists up in google searches. Only when you do explicit search.
> E.g. zip it.
> And move it from place so obsolete or forgotten links become dead links.
> This reminds that relative links can be usefull instead of full path links.


Once Google picks it up, the algorithm will prioritize serving up a cached copy. That is because otherwise, you'd have to go through something like CloudFlare EVERY SINGLE TIME just to make sure the host with the document is still up, and serving that very document. Sorry, just the way Internet is designed... there's only so many trans-oceanic cables that can be laid and maintained.


----------



## grahamperrin@ (Jun 25, 2021)

scottro said:


> … not quite up to date but better than 2001. …



It's a 2021-01-18 edition (PDF property: 2021-01-24). The Abstract page refers to <https://cgit.freebsd.org/doc/commit/?id=0d4371e5cc>. 

Subsequent editions to the corresponding page online: <https://cgit.freebsd.org/doc/log/documentation/content/en/books/handbook/_index.adoc>

From <https://docs-dev.freebsd.org/en/books/handbook/#preamble>: 



> … Some sections might be outdated. Those interested in helping to update and expand this document should send email to the FreeBSD documentation project mailing list.
> … Previous versions can be obtained from …


----------



## Terry_Kennedy (Jun 25, 2021)

Alain De Vos said:


> Yes backup old stuff, but only for archeological purposes.
> And somehow prevent that it lists up in google searches. Only when you do explicit search.
> E.g. zip it.


Including the those directories in robots.txt to prevent them from being indexed by search engines (preferably without excluding the Internet Archive) might work.

Another idea is that when old versions are archived, either an additional page or a text overlay could be added that says that this is a historical version, with info on where to find the current version. Those are quite easy to accomplish for PDF files, but I'm not sure about other files. OTOH, if my suggestions here are followed, new versions will automatically have that info included going forward and will eventually be archived.

I don't think there's anything that can be done about individual files that are out-of-date being mirrored elsewhere. If the complete documentation tree is mirrored somewhere else, a polite note from the doc team to that webmaster might fix things. Of course, we have to get our own house in order first.


----------



## kjpetrie (Jul 3, 2021)

I followed the link at the top of this forum to read the instructions for upgrading from 11.4 to 13.0 in the handbook.

Under 15.6.4  I read:
"15.6.4.1. Updating the Operating System" which includes:


> After updating the basejail, mergemaster(8) must be run to update each jail’s configuration files....


Instructions follow on how to do that, and hit an error, leaving me perplexed how to complete the upgrade on my jails. It's only adding a line to 3 files in each jail, so far as I can see, but it's still unnecessarily complicated for the user to do that using vi.


----------



## Alain De Vos (Jul 3, 2021)

You must do it stepwise ...


----------



## grahamperrin@ (Jul 3, 2021)

kjpetrie said:


> … unnecessarily complicated for the user to do that using vi.



I prefer editors/nano: 


```
root@mowa219-gjp4-8570p:~ # grep -e EDITOR -e VISUAL ~/.cshrc
setenv  EDITOR  /usr/local/bin/nano
setenv  VISUAL  /usr/local/bin/nano
# setenv        EDITOR  /usr/bin/vi
# setenv        VISUAL  /usr/bin/vi
root@mowa219-gjp4-8570p:~ #
```

YMMV; ee(1) is integral to the system.


----------



## Alain De Vos (Jul 3, 2021)

or featherpad or leafpad.


----------



## grahamperrin@ (Nov 11, 2021)

dvl@ said:


> … the PR …



We now have use of etcupdate(8) instead of mergemaster(8) under <https://cgit.freebsd.org/src/tree/UPDATING?id=e641c29a006ae9f528f196386052355b42a53d75#n2455>

Related: yesterday's <https://cgit.freebsd.org/src/commit/UPDATING?id=e641c29a006ae9f528f196386052355b42a53d75>


----------

