MFP4: Add the "Early Adopter's Guide to FreeBSD 5.0-RELEASE"

from the releng Perforce repository.  (Not hooked up to the RELNOTESng
build yet.)

	Makefile#1
	article.sgml#6

Reviewed by:	re

2 files changed, 432 insertions, 0 deletions

diff --git a/release/doc/en_US.ISO8859-1/early-adopter/Makefile b/release/doc/en_US.ISO8859-1/early-adopter/Makefile
new file mode 100644
index 0000000..a237b09
--- /dev/null
+++ b/release/doc/en_US.ISO8859-1/early-adopter/Makefile
@@ -0,0 +1,14 @@
+# $FreeBSD$
+
+DOC?= article
+
+FORMATS?= html
+
+INSTALL_COMPRESSED?=gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.sgml
+
+DOC_PREFIX?= /usr/doc
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/release/doc/en_US.ISO8859-1/early-adopter/article.sgml b/release/doc/en_US.ISO8859-1/early-adopter/article.sgml
new file mode 100644
index 0000000..d19eaaa
--- /dev/null
+++ b/release/doc/en_US.ISO8859-1/early-adopter/article.sgml
@@ -0,0 +1,418 @@
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
+%man;
+
+<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
+%freebsd;
+
+<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
+%authors;
+
+<!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
+%teams;
+
+<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
+%mailing-lists;
+]>
+
+<article>
+  <articleinfo>
+    <title>Early Adopter's Guide to FreeBSD 5.0-RELEASE</title>
+
+    <authorgroup>
+      <corpauthor>The FreeBSD Release Engineering Team</corpauthor>
+    </authorgroup>
+
+    <pubdate>$FreeBSD$</pubdate>
+
+    <copyright>
+      <year>2002</year>
+      <holder role="mailto:re@FreeBSD.org">The FreeBSD Release
+        Engineering Team</holder>
+    </copyright>
+  </articleinfo>
+
+  <section>
+    <title>Introduction</title>
+
+    <para>FreeBSD 5.0 marks the first new major version of FreeBSD in
+      over two years.  Besides a number of new features, it also
+      contains a number of major developments in the underlying system
+      architecture.
+      Along with these advances, however, comes a system that
+      incorporates a tremendous amount of new and not-widely-tested
+      code.  Compared to the existing line of
+      4.<replaceable>X</replaceable> releases, 5.0 may have regressions
+      in areas of stability, performance, and occasionally
+      functionality.</para>
+
+    <para>For these reasons, the &a.re; does <emphasis>not</emphasis>
+      encourage users to blindly update from older FreeBSD releases to
+      5.0.  Specifically, for more conservative users, we recommend
+      running 4.<replaceable>X</replaceable> releases (such as
+      4.7-RELEASE or the upcoming 4.8-RELEASE) for the near-term
+      future.  We feel that such users are probably best served by
+      upgrading to 5.<replaceable>X</replaceable> only after a
+      5-STABLE development branch has been created; this may be around
+      the time of 5.1-RELEASE or 5.2-RELEASE.</para>
+
+    <para>(FreeBSD 5.0 suffers from what has been described as a
+      <quote>chicken and egg</quote> problem.  The entire project has
+      a goal of producing a 5.0-RELEASE that is as stable and reliable
+      as possible.  This stability and reliability requires widespread
+      testing, particularly of the system's newer features.  However,
+      getting a large number of users to test the system, in a
+      practical sense, means building and distributing a
+      release first!)</para>
+
+    <para>This article describes some of the issues involved in
+      installing and running FreeBSD 5.0-RELEASE.  We begin with a
+      brief overview of the FreeBSD release process.  We then present
+      some of the more noteworthy new features in FreeBSD 5.0, along
+      with some areas that may prove troublesome for unwary users.
+      For those users choosing to remain with 4-STABLE-based releases,
+      we give some of the short- to medium-term plans for this
+      development branch.  Finally, we present some notes on upgrading
+      existing 4.<replaceable>X</replaceable> systems to 5.0.</para>
+
+  </section>
+
+  <section>
+    <title>An Overview of the FreeBSD Release Process</title>
+
+    <para>FreeBSD employs a model of development that relies on multiple
+      development branches within the source code repository.  The main branch is called
+      <quote>CURRENT</quote>, and is referred to in the CVS repository
+      with the <literal>HEAD</literal> tag.  New features are
+      committed first to this branch; although this means that CURRENT
+      is the first to see new functionality, it also means that it
+      occasionally suffers from breakages as new features are
+      added and debugged.</para>
+
+    <para>Most FreeBSD releases are made from one of several
+      <quote>STABLE</quote> branches.  Features are only added to
+      these branches after some amount of testing in CURRENT.  At the
+      moment, only one STABLE branch is under active development; this
+      branch is referred to as <quote>4-STABLE</quote>, and all of the
+      FreeBSD 4.<replaceable>X</replaceable> releases were based on
+      it.  This branch has the tag <literal>RELENG_4</literal> in the
+      CVS repository.</para>
+
+    <para>FreeBSD 5.0 will be based on the CURRENT branch.  This
+      will be the first release from this branch in over two years (the
+      last was FreeBSD 4.0, in March 2000).</para>
+
+    <para>At some point after the release of FreeBSD 5.0, a
+      <quote>5-STABLE</quote> branch will be created in the FreeBSD
+      CVS repository with the branch tag <literal>RELENG_5</literal>.
+      The past two stable branches (3-STABLE and 4-STABLE) were
+      created immediately after their respective <quote>dot-oh</quote>
+      releases (3.0 and 4.0, respectively).  In hindsight, this
+      practice did not give sufficient time for either CURRENT or the new
+      STABLE branches to stabilize after the new branches were
+      created.</para>
+
+    <para>Therefore, the release engineering team will only create the
+      5-STABLE branch in the CVS repository after they have found a
+      relatively stable state to use as its basis.  It is likely that
+      there will be 
+      multiple releases in the 5.<replaceable>X</replaceable> series
+      before this happens; we estimate
+      that the 5-STABLE branch will be created sometime after
+      5.1-RELEASE or 5.2-RELEASE.</para>
+
+    <para>More information on FreeBSD release engineering processes can be found
+      on the <ulink
+      url="http://www.FreeBSD.org/releng/index.html">Release
+      Engineering Web pages</ulink> and in the FreeBSD <ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/index.html">Release
+      Engineering</ulink> article.</para>
+
+  </section>
+
+  <section>
+    <title>New Features</title>
+
+    <para>A large attraction of FreeBSD 5.0 is a number of new
+      features.  These new features and functionality generally involve
+      large architectural changes that were not feasible to port back to
+      the FreeBSD 4-STABLE development branch.  (By contrast, many
+      self-contained enhancements, such as new device drivers or
+      userland utilities, have already been ported.)  A brief, but not
+      exhaustive list includes:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>SMPng: The <quote>next generation</quote> support for
+ 	  SMP machines (work in progress).  There is now partial
+ 	  support for multiple processors to be running in the kernel
+ 	  at the same time.</para>
+      </listitem>
+
+      <listitem>
+	<para>KSE:  Kernel Scheduled Entities allow a single process
+	  to have multiple kernel-level threads, similar to Scheduler
+	  Activations.</para>
+      </listitem>
+
+      <listitem>
+	<para>New architectures:  Support for the sparc64 and ia64
+	  architectures, in addition to the i386, pc98, and
+	  alpha.</para>
+      </listitem>
+
+      <listitem>
+	<para>GCC:  The compiler toolchain is now based on GCC
+	  3.<replaceable>X</replaceable>, rather than GCC
+	  2.95.<replaceable>X</replaceable>.</para>
+      </listitem>
+
+      <listitem>
+	<para>MAC:  Support for extensible, loadable Mandatory Access
+	  Control policies.</para>
+      </listitem>
+
+      <listitem>
+        <para>GEOM:  A flexible framework for transformations of disk
+	  I/O requests.  An experimental disk encryption facility has
+	  been developed based on GEOM.</para>
+      </listitem>
+
+      <listitem>
+	<para>FFS: The FFS filesystem now supports background
+          &man.fsck.8; operations (for faster crash recovery) and
+          filesystem snapshots.</para>
+      </listitem>
+
+      <listitem>
+	<para>UFS2:  A new UFS2 on-disk format has been added, which
+	  supports extended per-file attributes and larger file
+	  sizes.</para>
+      </listitem>
+
+      <listitem>
+        <para>Cardbus:  Support for Cardbus devices.</para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>A more comprehensive list of new features can be found in
+      the release notes for FreeBSD 5.0.</para>
+
+  </section>
+
+  <section>
+    <title>Drawbacks to Early Adoption</title>
+
+    <para>Along with the new features of FreeBSD 5.0 come some areas
+      that can cause problems, or at least can lead to unexpected
+      behavior.  Generally, these come from the fact that a number of
+      features are works-in-progress.  A partial list of these
+      areas of difficulty includes:</para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>A number of features are not yet finished.  Examples
+	  from the feature list above include SMPng and KSE.</para>
+      </listitem>
+
+      <listitem>
+        <para>Because of changes in kernel data structures and
+          ABIs/APIs, third-party binary device drivers will require
+          modifications to work correctly under FreeBSD 5.0.</para>
+      </listitem>
+
+      <listitem>
+        <para>Several parts of FreeBSD's base system functionality
+          have been moved to the Ports Collection.  Notable examples
+          include <application>Perl</application>,
+          <application>UUCP</application>, and most (but not all)
+          games.  While these programs are still supported, their
+          removal from the base system may cause some confusion.</para>
+      </listitem>
+
+      <listitem>
+        <para>A number of ports and packages do not build or do not
+          run correctly under FreeBSD 5.0, whereas they did under FreeBSD
+          4-STABLE.  Generally these problems are caused by compiler
+          toolchain changes or cleanups of header files.</para>
+      </listitem>
+
+      <listitem>
+        <para>Because FreeBSD 5.0 is the first release from the
+          CURRENT branch in over two years, many of its features are
+          seeing wide exposure for the first time.  Many of these
+          features (such as SMPng) have broad impacts on the
+          kernel.</para>
+      </listitem>
+
+      <listitem>
+        <para>A certain amount of debugging and diagnostic code is
+          still in place to help track down problems in FreeBSD 5.0's new
+          features.  This may cause FreeBSD 5.0 to perform more slowly
+          than 4-STABLE.</para>
+      </listitem>
+
+      <listitem>
+        <para>Features are only added to the 4-STABLE development
+          branch after a <quote>settling time</quote> in -CURRENT.
+          FreeBSD 5.0 does not have the stabilizing influence of a
+          -STABLE branch.  (It is likely that the 5-STABLE development
+          branch will be created sometime after 5.1-RELEASE or
+          5.2-RELEASE.)</para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>Because a number of these drawbacks affect system stability, the
+      release engineering team recommends that more conservative sites
+      and users stick to releases based on the 4-STABLE branch until
+      the 5.<replaceable>X</replaceable> series is more polished.</para>
+
+  </section>
+
+  <section>
+    <title>Plans for the 4-STABLE Branch</title>
+
+    <para>The release of FreeBSD 5.0 does not mean the end of the
+      4-STABLE branch.  There will be at least one more release on
+      this branch, namely 4.8-RELEASE, currently scheduled for 1
+      February 2003.</para>
+
+    <para>As of this writing, the release engineering team has no
+      definite plans for future releases (past 4.8) on the 4-STABLE
+      branch.  However, a 4.9-RELEASE or even a 4.10-RELEASE are
+      likely possibilities.  Any future releases from this branch will
+      depend on several factors.  The most important of these
+      is the existence and stability of the 5-STABLE branch.  If
+      CURRENT is not sufficiently stable to allow the creation of a
+      5-STABLE branch, this may require and permit more releases from
+      the 4-STABLE branch.  Until the last declared release
+      on the 4-STABLE branch, new features may be merged from HEAD at
+      the discretion of developers, subject to existing release
+      engineering policies.</para>
+
+    <para>To some extent, the release engineering team will take into
+      account user demand for future 4-STABLE releases.  This demand,
+      however, will need to be balanced with release engineering
+      resources (in terms of personnel, computing resources, and mirror
+      archive space).</para>
+
+    <para>The &a.security-officer; will continue to support releases
+      made from the 4-STABLE branch in accordance with their published
+      policies, which can be found on the <ulink
+      url="http://www.FreeBSD.org/security/index.html">Security
+      page</ulink> on the FreeBSD web site.  Generally, the two most
+      recent releases from any branch will be supported with respect
+      to security advisories and security fixes.  At its discretion,
+      the team may support other releases.</para>
+
+  </section>
+
+  <section>
+    <title>Notes on Upgrading</title>
+
+    <para>For those users with existing FreeBSD systems, this section
+      offers a few notes on upgrading a FreeBSD
+      4.<replaceable>X</replaceable> system to
+      5.<replaceable>X</replaceable>.  As with any FreeBSD upgrade, it
+      is crucial to read the release notes and the errata for the
+      version in question, as well as
+      <filename>src/UPGRADING</filename> for source upgrades.</para>
+
+    <section>
+      <title>Binary Upgrades</title>
+
+      <para>Probably the most straightforward approach is that of
+        <quote>backup everything, reformat, reinstall, and restore
+        everything</quote>.  This eliminates problems of incompatible
+        or obsolete executables or configuration files polluting the
+        new system.</para>
+
+      <para>As of this time, the binary upgrade option in
+        &man.sysinstall.8; has not been well-tested for
+        cross-major-version upgrades.  Using this feature is not
+        recommended.</para>
+
+      <para>On the i386 and pc98 platforms, a UserConfig utility
+        exists on 4-STABLE to allow boot-time configuration of ISA
+        devices when booting from installation media.  Under FreeBSD
+        5.0, this functionality has been replaced in part by the
+        &man.device.hints.5; mechanism (it allows specifying the same
+        parameters, but is not interactive).</para>
+
+      <para>Floppy-based binary installations may require downloading
+        a third, new floppy image holding additional device drivers
+        in kernel modules.  This <filename>drivers.flp</filename>
+        floppy image will generally be found in the same location as
+        the usual <filename>kern.flp</filename> and
+        <filename>mfsroot.flp</filename> floppy images.</para>
+
+      <para>CDROM-based installations on the i386 architecture now use
+        a <quote>no-emulation</quote> boot loader.  This allows, among
+        other things, the use of a <literal>GENERIC</literal> kernel,
+        rather than the stripped-down kernel on the floppy images.  In
+        theory, any system capable of booting the Microsoft Windows NT
+        4 installation CDROMs should be able to cope with the FreeBSD
+        5.0 CDROMs.</para>
+
+    </section>
+
+    <section>
+      <title>Source Upgrades</title>
+
+      <para>Reading <filename>src/UPDATING</filename> is absolutely
+        essential.  The section entitled <quote>To upgrade from
+        4.x-stable to current</quote> contains a step-by-step update
+        procedure.  This procedure must be followed exactly, without
+        using of the <quote>shortcuts</quote> that some users
+        occasionally employ.</para>
+
+    </section>
+
+    <section>
+      <title>Common Notes</title>
+
+      <para><application>Perl</application> has been removed from the
+        base system.  The recommended way of installing Perl is either
+        from a pre-built package or from the Ports Collection.
+        Building Perl as a part of the base system created a number of
+        difficulties which made updates problematic.  
+        The base system utilities that used Perl have either
+        been rewritten (if still applicable) or discarded (if
+        obsolete).</para>
+
+      <para>It is generally possible to run old
+        4.<replaceable>X</replaceable> executables under
+        5.<replaceable>X</replaceable>, but this requires the
+        <filename>compat4x</filename> distribution to be installed.
+        Thus, using old ports <emphasis>may</emphasis> be
+        possible.</para>
+
+      <para>When installing or upgrading over the top of an existing
+        4-STABLE-based system, it is extremely important to clear out
+        old header files in <filename>/usr/include</filename>.
+        Renaming or moving this directory before a binary installation
+        or an <literal>installworld</literal> is generally
+        sufficient.  If this step is not taken, confusion may result
+        (especially with C++ programs) as the compiler may wind up
+        using a mixture of obsolete and current header files.</para>
+
+    </section>
+
+  </section>
+
+  <section>
+
+    <title>Summary</title>
+
+    <para>While FreeBSD 5.0 contains a number of new and exciting
+      features, it may not be suitable for all users at this time.  In
+      this document, we presented some background on release
+      engineering, some of the more notable new features of the 5.0
+      series, and some drawbacks to early adoption.  We also presented
+      some future plans for the 4-STABLE development branch and some
+      tips on upgrading for early adopters.</para>
+
+  </section>
+</article>