The "When switching from mergemaster(8) to etcupdate(8)" text appears twice in https://docs.freebsd.org/en/books/handbook/cutting-edge/ $ grep -B3 -A2 'When switching from man:mergemaster' documentation/content/en/books/handbook/cutting-edge/_index.adoc [WARNING] ==== When switching from man:mergemaster[8] to man:etcupdate[8], the first run might merge changes incorrectly generating spurious conflicts. To prevent this, perform the following steps *before* updating sources and building the new world: -- [WARNING] ==== When switching from man:mergemaster[8] to man:etcupdate[8], the first run might merge changes incorrectly generating spurious conflicts. To prevent this, perform the following steps *before* updating sources and building the new world:
Relevant commits: 7859bada695 - first added dfde7327ba0 - etcupdate bootstrap corrected to etcupdate extract 313c8a75f1c - corrected comma splice and introduced duplicate content 51b500976a2 - typo correction in duplicate content
In my opinion, keeping the warning twice seems good. Both places (at the top of the section and when merging with etcupdate) are good places to warn the users and prevent them from incorrect migration from etcupdate to mergemaster. However, if the one of them has to be removed, I would like to keep the first one.
(In reply to Minsoo Choo from comment #2) I agree it's important to reference this in both places -- before starting the upgrade (when the steps need to be taken) and at the point in the process where it is important that the steps have been taken, and I agree that the first is the most important one. But I think the exact same text should not appear twice - the second location should have a note and cross-reference to the first.