Page MenuHomeFreeBSD

Try to favor etcupdate(8) over mergemaster(8) in the handbook
ClosedPublic

Authored by driesm.michiels_gmail.com on Dec 30 2020, 2:56 PM.

Details

Summary

Explain we also have etcupdate and prefer it over mergemaster.

Test Plan
  • Read the chapter
  • igor chapter.xml

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

driesm.michiels_gmail.com retitled this revision from Try to favor etcupdate over mergemsater in the handbook to Try to favor etcupdate(8) over mergemsater(8) in the handbook.Dec 30 2020, 3:35 PM
driesm.michiels_gmail.com retitled this revision from Try to favor etcupdate(8) over mergemsater(8) in the handbook to Try to favor etcupdate(8) over mergemaster(8) in the handbook.
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
1201 ↗(On Diff #81373)

etcupdate -B here is actually a bit quicker as it uses the files from the built world to populate the temp root. (It is a no-op for -p)

I don't actually use -F in practice myself, but it's fine to recommend it by default. It will soon cease to matter since git doesn't update the strings anyway.

1576 ↗(On Diff #81373)

s/more preferred/preferred/. Another way to frame it may be that mergemaster is an older tool and legacy installs may still need to use it to keep up to date.

In general with etcupdate it would be nice to have a warning or headsup somewhere that running 'etcupdate diff' and making sure the diff looks ok is good before using it for the first time. If the diff shows a lot of unexpected changes then etcupdate may do surprising things. Also, if you start using etcupdate on a system that has been managed via mergemaster, the first run of etcupdate may report some bogus conflicts due to already-applied changes. It might be good to add a section about switching from one scheme to the other somewhere. In general what you would want to do in that case is:

run 'etcupdate diff' _before_ updating your sources and building the new world + kernel. If it shows lots of diffs you don't expect, then run 'etcupdate bootstrap' and compare 'etcupdate diff' again. Any diffs should now be real changes compared to the stock files. If necessary, manually update files in /etc to remove undesired local changes. Then proceed to update the source tree and build world, etc.

Remove files not intended to be added to the review.

driesm.michiels_gmail.com added inline comments.
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
1201 ↗(On Diff #81373)

I was doubting myself to recommend -F or not given the tags wont remain, in the end I left it out.

1576 ↗(On Diff #81373)

Added a note to use "etcupdate diff" as a go to before running the actual command. Also added a warning regarding the first use of etcupdate and the bogus conflicts.

I think this is ok, but I've also added @ngie to the review.

en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
1198 ↗(On Diff #81414)

nit: this indentation seems off.

1555–1556 ↗(On Diff #81414)
1566–1567 ↗(On Diff #81414)

This wording seems a bit indirect.

end-user might need to be replaced with something that matches other surrounding descriptions.

1621–1623 ↗(On Diff #81414)

These seem like 2 separate thoughts that should be separate sentences.

driesm.michiels_gmail.com added inline comments.
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
1198 ↗(On Diff #81414)

Indeed!

1621–1623 ↗(On Diff #81414)

I was actually doubting if we should still mention that: "mergemaster might be needed for older systems". In this revision I left it out as it comes over a bit undecided. If we would like to deprecate mergemaster and remove it from base at one point in time a comment like that isn't very helpful for that plan. From my point of view all supported releases can be updated with etcupdate.

driesm.michiels_gmail.com marked 2 inline comments as done.

Rebase on new documentation. Not yet build tested.

Fix some other typo's.
I have build tested it and looks good in the web browser.

documentation/content/en/books/handbook/cutting-edge/_index.adoc
897–912

I think it might be simpler and less confusing to just tell users switching to etcupdate to always do a bootstrap first.

Advise to always run the bootstrap procedure when switching from mergemaster(8).

This revision is now accepted and ready to land.Feb 17 2021, 11:25 PM
debdrup added a subscriber: debdrup.

The only thing I'd note is that [source,bash] should be [source,shell].

If you're okay with me commiting this, I'll do a pass on the whole file as a separate commit, then rebase this change onto a branch, do a second pass, rebase to main and push everything.

@debdrup given I don't have a commit bit someone will have to do it in my place anyway :-).
I like your suggested approach, go ahead & thank you for getting this landed!

The patch doesn't apply cleanly for me, and it doesn't look like a trivial fix.

Here's a log.

Can you please rebase your patch, and upload it again?

This revision now requires review to proceed.Mar 26 2021, 8:27 PM

Change [source,bash] to [source,shell]

The only thing I'd note is that [source,bash] should be [source,shell].

Done & thanks!

This revision was not accepted when it landed; it landed in state Needs Review.Mar 26 2021, 10:01 PM
This revision was automatically updated to reflect the committed changes.