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

[driesm]

Summary

Explain we also have etcupdate and prefer it over mergemaster.

Test Plan

• Read the chapter
• igor chapter.xml

[jhb]

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.

[driesm]

Update with feedback from jhb.

[driesm]

Remove files not intended to be added to the review.

[driesm]

Remove unwanted whitespace line.

[driesm]

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.

[jhb]

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

[ngie]

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]

Incorporate feedback.

[driesm]

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]

Rebase on new documentation. Not yet build tested.

[driesm]

• Fix typo agains => again

[driesm]

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

[jhb]

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

864–879

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

[driesm]

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

[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.

[driesm]

@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!

[debdrup]

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?

[driesm]

Rebase on top of master

[driesm]

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

[driesm]

In D27848#656645, @debdrup wrote:

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

Done & thanks!