Bug 206866 - [handbook] Replace mergemaster(8) with newer etcupdate(8) utility for source upgrades
Summary: [handbook] Replace mergemaster(8) with newer etcupdate(8) utility for source ...
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Warren Block
URL: https://reviews.freebsd.org/D7665
Keywords:
Depends on:
Blocks:
 
Reported: 2016-02-03 00:47 UTC by Ben Woods
Modified: 2018-05-28 19:43 UTC (History)
4 users (show)

See Also:


Attachments
Patch to update handbook to replace mergemaster(8) with etcupdate(8) (18.54 KB, patch)
2016-02-03 00:51 UTC, Ben Woods
no flags Details | Diff
QA: Successully built makeworld.html section from handbook (with proposed changes) (48.60 KB, text/html)
2016-02-03 00:53 UTC, Ben Woods
no flags Details
Patch to update handbook to replace mergemaster(8) with etcupdate(8) (23.99 KB, patch)
2016-02-07 21:29 UTC, Ben Woods
no flags Details | Diff
QA: Successully built makeworld.html section from handbook (with proposed changes) (52.96 KB, text/html)
2016-02-07 21:31 UTC, Ben Woods
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Ben Woods freebsd_committer 2016-02-03 00:47:39 UTC
The attached patch updates chapter 23 of the FreeBSD Handbook for "Updating and Upgrading FreeBSD" to replace all references to the mergemaster(8) utility with the newer etcupdate(8) utility when performing source upgrades.

The benefit of the etcupdate(8) utility is that it provides 3-way merge functionality, meaning that the user does not need to review every difference between the new configuration file from the source tree and that already installed on the running system if they can be automatically merged.

This change was recommended by feld@ and des@ on Twitter.
Comment 1 Ben Woods freebsd_committer 2016-02-03 00:51:36 UTC
Created attachment 166466 [details]
Patch to update handbook to replace mergemaster(8) with etcupdate(8)
Comment 2 Ben Woods freebsd_committer 2016-02-03 00:53:34 UTC
Created attachment 166467 [details]
QA: Successully built makeworld.html section from handbook (with proposed changes)

Requires docbook.css to be in same folder for correct styling.
Comment 3 Dag-Erling Smørgrav freebsd_committer 2016-02-07 12:56:39 UTC
> Modified to use the newer etcupdate(8) utility by Ben Woods.

It doesn't *use* anything.  It *describes* etcupdate(8).

> Note that etcupdate has replaced mergemaster(8) [...] as the latter
> required the user to review all of the differences [...]

That's not true.  With the correct configuration, mergemaster(8) is
just as easy to use as etcupdate(8) in most cases.  The main
(user-visible) difference is that etcupdate(8) does three-way merges,
which make conflict resolution much easier.

> If it shows an unexpected result, or if it fails with an error about
> a missing reference tree, then it is likely that etcupdate needs to
> be bootstrapped.

It only needs to be bootstrapped if it says it hasn't been already.
If it shows an "unexpected result" that isn't an error, then you've
either bootstrapped it from a source tree that doesn't match your
running system or simply not run it after your last update.

> svn checkout -r YOURREVISION https://svn.FreeBSD.org/base/head/
> /PATH/TO/SAVE/SOURCE/TREE

Since you're building from source, it's reasonable to assume that you
already have a working copy.  In that case, it is faster to revert it
to the correct version than to check out a new copy.  Also, svn:// is
faster than https://, and don't assume that people are running head.

> Before using etcupdate, it is recommended to have a backup or
> snapshot of /etc.

It's probably not a bad idea, but I'm uncomfortable with actually
recommending it.  It gives the reader the impression that etcupdate is
unreliable.

Finally, and most importantly, you don't describe how to resolve
conflicts ('etcupdate merge').
Comment 4 Dag-Erling Smørgrav freebsd_committer 2016-02-07 17:06:16 UTC
> > Note that etcupdate has replaced mergemaster(8) [...] as the
> > latter required the user to review all of the differences [...]
> That's not true.  [...]

I left out my main point here, which is that it is completely
unnecessary, in my opinion, to explain *why* mergemaster(8) is being
replaced.

> Finally, and most importantly, you don't describe how to resolve
> conflicts ('etcupdate merge').

Sorry, 'etcupdate resolve' of course.
Comment 5 Ben Woods freebsd_committer 2016-02-07 21:29:45 UTC
Created attachment 166719 [details]
Patch to update handbook to replace mergemaster(8) with etcupdate(8)

Thanks for looking at this patch DES, and for providing feedback. I have updated my patch (attached) and believe I have addressed each of your comments. Please let me know if you have any further comments.
Comment 6 Ben Woods freebsd_committer 2016-02-07 21:31:30 UTC
Created attachment 166720 [details]
QA: Successully built makeworld.html section from handbook (with proposed changes)
Comment 7 Ben Woods freebsd_committer 2016-03-18 07:35:40 UTC
Hi DES,
I'm hoping to get this committed into the handbook, and I'm open to making changes if it's not quite right.
Would you mind taking another look and let me know if you have any comments?
Thanks,
Ben
Comment 8 Ben Woods freebsd_committer 2016-08-29 14:30:46 UTC
Comment on attachment 166719 [details]
Patch to update handbook to replace mergemaster(8) with etcupdate(8)

Warren Block has proposed a complete overhaul of the "updating from source" section of the handbook, which simplifies the chapter significantly and includes details of etcupdate(8).
https://reviews.freebsd.org/D7665

Suggest Warren's work is more applicable than this patch, and therefore marking this patch as obsolete. People can still refer back to this patch for wording if needed for the updated chapter.
Comment 9 Eitan Adler freebsd_committer freebsd_triage 2018-05-28 19:43:49 UTC
batch change:

For bugs that match the following
-  Status Is In progress 
AND
- Untouched since 2018-01-01.
AND
- Affects Base System OR Documentation

DO:

Reset to open status.


Note:
I did a quick pass but if you are getting this email it might be worthwhile to double check to see if this bug ought to be closed.