From b.candler@pobox.com  Mon Nov 22 10:18:03 2004
Return-Path: <b.candler@pobox.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 047A816A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 22 Nov 2004 10:18:02 +0000 (GMT)
Received: from boggle.pobox.com (boggle.pobox.com [208.58.1.193])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 5E86643D39
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 22 Nov 2004 10:18:02 +0000 (GMT)
	(envelope-from b.candler@pobox.com)
Received: from boggle (localhost [127.0.0.1])
	by boggle.pobox.com (Postfix) with ESMTP id 13318AE1A2
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 22 Nov 2004 05:18:02 -0500 (EST)
Received: from billdog.local.linnet.org (dsl-212-74-113-65.access.uk.tiscali.com [212.74.113.65])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by boggle.sasl.smtp.pobox.com (Postfix) with ESMTP id 7F34541BF11
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 22 Nov 2004 05:18:01 -0500 (EST)
Received: from brian by billdog.local.linnet.org with local (Exim 4.43 (FreeBSD))
	id 1CWBGi-000O56-FO
	for FreeBSD-gnats-submit@freebsd.org; Mon, 22 Nov 2004 10:18:00 +0000
Message-Id: <E1CWBGi-000O56-FO@billdog.local.linnet.org>
Date: Mon, 22 Nov 2004 10:18:00 +0000
From: Brian Candler <b.candler@pobox.com>
Reply-To: Brian Candler <b.candler@pobox.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Conflicting information on mergemaster -p
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         74231
>Category:       docs
>Synopsis:       Conflicting information on mergemaster -p
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Nov 22 10:20:22 GMT 2004
>Closed-Date:    Thu Dec 23 18:02:40 GMT 2004
>Last-Modified:  Mon Dec 27 12:30:22 GMT 2004
>Originator:     Brian Candler
>Release:        FreeBSD 5.3-STABLE i386
>Organization:
>Environment:
System: FreeBSD billdog.local.linnet.org 5.3-STABLE FreeBSD 5.3-STABLE #3: Thu Nov 18 15:49:59 GMT 2004 root@billdog.local.linnet.org:/usr/src/sys/i386/compile/BILLDOG i386


>Description:

The handbook gives inconsistent information about where 'mergemaster -p'
fits into the build/upgrade process.
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html

In section 19.4.1 its advice is the same as I find in /usr/src/Makefile:

# For individuals wanting to upgrade their sources (even if only a
# delta of a few days):
#
# 1.  `cd /usr/src'       (or to the directory containing your source tree).
# 2.  `make buildworld'
# 3.  `make buildkernel KERNCONF=YOUR_KERNEL_HERE'     (default is GENERIC).
# 4.  `make installkernel KERNCONF=YOUR_KERNEL_HERE'   (default is GENERIC).
# 5.  `reboot'        (in single user mode: boot -s from the loader prompt).
# 6.  `mergemaster -p'
# 7.  `make installworld'
# 8.  `mergemaster'
# 9.  `reboot'
#
# See src/UPDATING `COMMON ITEMS' for more complete information.

However in section 19.4.4 it says that mergemaster -p should be done earlier
in the process; and section 19.4.10 doesn't suggest doing mergemaster -p
there, which would be consistent with the initial advice.

19.4.4 describes the -p flag as "pre-buildworld". 'man mergemaster' says the
same, and also says it "compares only files known to be essential to the
success of {build|install}world". That implies it may need to be done before
make buildworld, as well or instead of before make installworld.

>How-To-Repeat:
	
>Fix:

Make it clear where mergemaster -p should be done in the entire process:
is it ever required before buildworld, or only before installworld?

>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: Brian Candler <b.candler@pobox.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/74231: Conflicting information on mergemaster -p
Date: Mon, 22 Nov 2004 15:37:38 +0200

 On 2004-11-22 10:18, Brian Candler <b.candler@pobox.com> wrote:
 >
 > Make it clear where mergemaster -p should be done in the entire process:
 > is it ever required before buildworld, or only before installworld?
 
 AFAIK, mergemaster -p is only needed before installworld.  The makefile
 `magic' of the build process is smart enough to handle the buildworld
 stage without mergemaster's help.
 
 I could be wrong, but I have been running mergemaster -p only before
 installworld, while in single-user mode, for years now.  I don't recall
 any problems with that.
 
Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Thu Dec 23 00:41:15 GMT 2004 
Responsible-Changed-Why:  
I'll handle this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=74231 
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Thu Dec 23 17:59:19 GMT 2004 
State-Changed-Why:  
I've just committed a couple of short paragraphs stating that mergemaster may 
have to be run twice.  Once before buildworld and once after installworld. 
Hopefully, this will reduce the potential for confusion regarding the -p 
option of mergemaster. 

The changes should show up online within the next 24 hours.  Thanks for 
submitting this problem report. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=74231 

From: Brian Candler <B.Candler@pobox.com>
To: Giorgos Keramidas <keramida@FreeBSD.org>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/74231: Conflicting information on mergemaster -p
Date: Mon, 27 Dec 2004 12:25:50 +0000

 On Thu, Dec 23, 2004 at 06:02:39PM +0000, Giorgos Keramidas wrote:
 > Synopsis: Conflicting information on mergemaster -p
 > 
 > State-Changed-From-To: open->closed
 > State-Changed-By: keramida
 > State-Changed-When: Thu Dec 23 17:59:19 GMT 2004
 > State-Changed-Why: 
 > I've just committed a couple of short paragraphs stating that mergemaster may
 > have to be run twice.  Once before buildworld and once after installworld.
 > Hopefully, this will reduce the potential for confusion regarding the -p
 > option of mergemaster.
 > 
 > The changes should show up online within the next 24 hours.  Thanks for
 > submitting this problem report.
 > 
 > http://www.freebsd.org/cgi/query-pr.cgi?pr=74231
 
 Thank you. However I think the inconsistency remains in the webpage between
 the 'canonical way' and then the step-by-step instructions; this is because
 section 19.4.1 says to run
 
 # make buildworld
 # make buildkernel
 # make installkernel
 # reboot
 boot -s
 # mergemaster -p
 # make installworld
 # mergemaster
 # reboot
 
 (note: mergemaster -p before make installworld), whereas sections
 19.4.4-19.4.14 say that you should run
 
 # mergemaster -p			# 19.4.4
 # make buildworld			# 19.4.7.2
 # make buildkernel KERNCONF=MYKERNEL	# 19.4.8
 # make installkernel KERNCONF=MYKERNEL
 # reboot				# 19.4.9
 boot -s
 # make installworld			# 19.4.10
 # mergemaster				# 19.4.11
 # shutdown -r now			# 19.4.14
 
 (mergemaster -p before make buildworld).
 
 Perhaps the simplest solution here is that paragraph 19.4.4 should be moved
 so that it is between 19.4.9 and 19.4.10, so that the sequence is consistent
 with that given in 19.4.1, and also with /usr/src/UPDATING.
 
 Regards,
 
 Brian.
>Unformatted:
