docs/183246: FreeBSD 8.4-RELEASE Installation Instructions don't properly warn about the need to update all ports

Wed Oct 23 18:50:00 UTC 2013

>Number:         183246
>Category:       docs
>Synopsis:       FreeBSD 8.4-RELEASE Installation Instructions don't properly warn about the need to update all ports
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Oct 23 18:50:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     Stefan Lasiewski
>Release:        8.3-RELEASE-p3
>Organization:
Lawrence Berkeley National Laboratory
>Environment:
FreeBSD 8.3-RELEASE-p3 #0: Tue Jun 12 00:39:29 UTC 2012     root at amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC
>Description:
Summary:

The "FreeBSD 8.4-RELEASE Installation Instructions" at [1] suggests that I shouldn't need to update FreeBSD ports. However when I run `freebsd-update`, freebsd-update says that I *should* update all ports, which is an unwelcome surprise at this point in my maintenance window.

This conflict between the documentation and the reality needs to be resolved. I don't know if the proper fix is to update the documentation, fix freebsd-update or what. I'll leave that to you.

Details:

The following problem has been repeated on several systems, running everything from FreeBSD 8.0 to FreeBSD 9.2. For the purpose of this ticket I am using a FreeBSD 8.3 system.

I am updating from FreeBSD 8.3-RELEASE to 8.4-RELEASE, following the "FreeBSD 8.4-RELEASE Installation Instructions" at [1]. 

According to the instructions, since I am not running FreeBSD 7.4-RELEASE or earlier, I won't be prompted to rebuild all third-party applications on my system. The instructions say:

    At this point, users of systems being upgraded from FreeBSD 7.4-RELEASE or
    earlier will be prompted by freebsd-update to rebuild all third-party
    applications (e.g., ports installed from the ports tree) due to updates in
    system libraries.

However, in reality, `freebsd-update` tells me that I should now "rebuild all installed 3rd party software (e.g., programs installed from the ports tree)". I wasn't prepared to do this and it's a little late in the process for FreeBSD to be telling me that I need to compile a bunch of software.

This conflict between the documentation and the reality needs to be resolved. I don't know if the proper fix is to update the documentation, fix freebsd-update or what.

```
[root at node1 ~]# uname -a
FreeBSD 8.3-RELEASE-p3 #0: Tue Jun 12 00:39:29 UTC 2012     root at amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC
[root at node1 ~]# freebsd-update upgrade -r 8.4-RELEASE
Looking up update.FreeBSD.org mirrors... 5 mirrors found.
Fetching metadata signature for 8.3-RELEASE from update2.freebsd.org... done.
..
..
.. (Merge configuration files, etc)
..
..
[root at node1 ~]# freebsd-update install
Installing updates...
Kernel updates have been installed.  Please reboot and run
"/usr/sbin/freebsd-update install" again to finish installing updates.
[root at node1 ~]# shutdown -r now
Connection to node1.example.org closed by remote host.
Connection to node1.example.org closed.

# and then "After rebooting, freebsd-update(8) needs to be run again to install the new userland components:"

node1# /usr/sbin/freebsd-update install
Installing updates...
Completing this upgrade requires removing old shared object files.
Please rebuild all installed 3rd party software (e.g., programs
installed from the ports tree) and then run "/usr/sbin/freebsd-update install"
again to finish installing updates.
node1#
```

At this point I'm placed in the uncomfortable position-- do I press forward with upgrading all ports on the system and risk exceeding the time allowed by our maintenance window (Upgrading FreeBSD ports can easily take a hours, and introduces changes that we weren't expecting), do I roll back and declare my system maintenance a failure, leave my system hanging in this in-between state while I schedule a second maintenance window to do what `freebsd-update` tells me to do, ignore the warning, etc?

[1] http://www.freebsd.org/releases/8.4R/installation.html
>How-To-Repeat:
1. Have a system running 8.3-RELEASE
2. Run `freebsd-update upgrade -r 8.4-RELEASE`
>Fix:

>Release-Note:
>Audit-Trail:
>Unformatted: