freebsd-dev/release/doc/en_US.ISO8859-1/early-adopter/article.sgml

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

<!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN">
%release;

<!ENTITY release.4x "4.<replaceable>X</replaceable>">
<!ENTITY release.5x "5.<replaceable>X</replaceable>">

]>

<article>
  <articleinfo>
    <title>Early Adopter's Guide to &os; &release.current;</title>

    <authorgroup>
      <corpauthor>The &os; Release Engineering Team</corpauthor>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <copyright>
      <year>2002</year>
      <year>2003</year>
      <holder role="mailto:re@FreeBSD.org">The &os; Release
        Engineering Team</holder>
    </copyright>

    <abstract>
      <para>This article describes the status of &os;
	&release.current;, from the standpoint of users who may be new
	to the &release.5x; series of releases or to &os; in general.
	It presents some background information on release
	engineering, some highlights of new features, and some
	possible drawbacks that might be faced by early adopters.  It
	also contains some of the future release engineering plans for
	the 4-STABLE development branch and some tips on upgrading
	existing systems.</para>
    </abstract>
  </articleinfo>

  <sect1 id="intro">
    <title>Introduction</title>

    <para>&os; &release.5x; marks the first new major version of &os; 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
      &release.4x; releases, the first few &release.5x; releases
      may have regressions
      in areas of stability, performance, and occasionally
      functionality.</para>

    <para>For these reasons, the &a.re; specifically
      discourages users from updating from older &os; releases to
      &release.current; unless they are aware of (and prepared to deal
      with) possible regressions in the newer releases.
      Specifically, for more conservative users, we recommend
      running &release.4x; releases (such as
      4.8-RELEASE) for the near-term
      future.  We feel that such users are probably best served by
      upgrading to &release.5x; only after a
      5-STABLE development branch has been created; this may be around
      the time of 5.2-RELEASE.</para>

    <para>(&os; &release.5x; suffers from what has been described as a
      <quote>chicken and egg</quote> problem.  The entire project has
      a goal of producing releases that are 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 &os; &release.current;.  We begin with a
      brief overview of the &os; release process.  We then present
      some of the more noteworthy new features in &os; &release.current;, 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 &release.4x; systems to &release.current;.</para>

  </sect1>

  <sect1 id="release-overview">
    <title>An Overview of the &os; Release Process</title>

    <para>&os; 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 &os; 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
      &os; &release.4x; releases were based on
      it.  This branch has the tag <literal>RELENG_4</literal> in the
      CVS repository.</para>

    <para>&os; 5.0 and 5.1 are based on the CURRENT branch.  These
      are the first releases from this branch in over two years (the
      last was &os; 4.0, in March 2000).</para>

    <para>At some point after the release of &os; 5.0, a
      <quote>5-STABLE</quote> branch will be created in the &os;
      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
      to stabilize before the new branches were
      created.  This in turn resulted in wasted effort porting bug
      fixes between branches, as well as some architectural changes
      that could not be ported between branches at all.</para>

    <para>Therefore, the release engineering team will only create the
      5-STABLE branch in the CVS repository after we have found a
      relatively stable state to use as its basis.  It is likely that
      there will be 
      multiple releases in the &release.5x; series
      before this happens; we estimate
      that the 5-STABLE branch will be created sometime after
      5.2-RELEASE.</para>

    <para>More information on &os; 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 <ulink
      url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/index.html"><quote>&os; Release
      Engineering</quote></ulink> article.  Specific issues for the upcoming
      5-STABLE development branch can be found in <ulink
      url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/5-roadmap/index.html"><quote>The
      Roadmap for 5-STABLE</quote></ulink>.</para>

  </sect1>

  <sect1 id="new">
    <title>New Features</title>

    <para>A large attraction of &os; &release.5x; 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 &os; 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.  This work is ongoing.</para>
      </listitem>

      <listitem>
	<para>KSE:  Kernel Scheduled Entities allow a single process
	  to have multiple kernel-level threads, similar to Scheduler
	  Activations.  The (experimental) <filename>libkse</filename>
	  and <filename>libthr</filename> libraries make this
	  feature available to multi-threaded userland programs.</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.2.2, 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.  UFS2 is now the default format for &man.newfs.8;.
	  On all platforms except for pc98, filesystems created from
	  within &man.sysinstall.8; will use UFS2 by default.</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 &os; &release.prev; and &os; &release.current;.</para>

  </sect1>

  <sect1 id="drawbacks">
    <title>Drawbacks to Early Adoption</title>

    <para>Along with the new features of &os; &release.5x; 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.  While
	  suitable for testing and experimentation, these features may
	  not be ready for production use.</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 &os; 5.0.  There is
          a possibility of more minor ABI/API changes before the
          5-STABLE branch is created.</para>
      </listitem>

      <listitem>
        <para>Several parts of &os;'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>Some parts of the &os; base system have fallen into a
	  state of disrepair due to a lack of users and maintainers.
	  These have been removed.  Specific examples include the
	  generation of a.out-style executables, XNS networking
	  support, and the X-10 controller driver.</para>
      </listitem>

      <listitem>
        <para>A number of ports and packages do not build or do not
          run correctly under &os; 5.0, whereas they did under &os;
          4-STABLE.  Generally these problems are caused by compiler
          toolchain changes or cleanups of header files.</para>
      </listitem>

      <listitem>
        <para>Many &os; &release.5x; 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 &os; 5.0's new
          features.  This may cause &os; 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.
          &os; 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.2-RELEASE.)</para>
      </listitem>

      <listitem>
	<para>Documentation (such as the &os; <ulink
          url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/index.html">Handbook</ulink>
          and <ulink
          url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">FAQ</ulink>)
          may not reflect changes recently made to &os; &release.5x;.</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 &release.5x; series is more polished.</para>

  </sect1>

  <sect1 id="plans-stable">
    <title>Plans for the 4-STABLE Branch</title>

    <para>The release of &os; 5.0 does not mean the end of the
      4-STABLE branch.  Indeed, &os; 4.8 was released two months after
      5.0, in April 2003.  There will most likely be at least one more release on
      this branch, namely 4.9-RELEASE, currently scheduled for summer
      2003.
      A 4.10-RELEASE is a likely possibility as well.
      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 <literal>HEAD</literal> at
      the discretion of developers, subject to existing release
      engineering policies.</para>

    <para>To some extent, the release engineering team (as well as the
      developer community as a whole) will take into
      account user demand for future 4-STABLE releases.  This demand,
      however, will need to be balanced with release engineering
      resources (particularly developers' time, 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 &os; 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 for specific issues.</para>

  </sect1>

  <sect1 id="upgrade">
    <title>Notes on Upgrading from &os; &release.4x;</title>

    <para>For those users with existing &os; systems, this section
      offers a few notes on upgrading a &os;
      &release.4x; system to
      &release.5x;.  As with any &os; upgrade, it
      is crucial to read the release notes and the errata for the
      version in question, as well as
      <filename>src/UPDATING</filename> in the case of source upgrades.</para>

    <sect2>
      <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.  It allows new filesystems to be created to take
        advantage of new functionality (most notably, the UFS2
        defaults).</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.  In particular, a binary upgrade will leave
        behind a number of files that are present in &os;
        &release.4x; but not in &release.5x;.  These obsolete
        files may create some problems.</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 &os;
        5.0, this functionality has been replaced in part by the
        &man.device.hints.5; mechanism (it allows specifying the same
        parameters, but with a very different interface).</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 &os;
        &release.5x; CDROMs.</para>

    </sect2>

    <sect2>
      <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
        making use of the <quote>shortcuts</quote> that some users
        occasionally employ.</para>

    </sect2>

    <sect2>
      <title>Common Notes</title>

      <para><application>Perl</application> has been removed from the
        base system, and should be installed 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).  &man.sysinstall.8; will now install the
        Perl package as a part of most distribution sets, so most
        users will not notice this change.</para>

      <para>It is generally possible to run old
        &release.4x; executables under
        &release.5x;, 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>

      <para><filename>MAKEDEV</filename> is no longer available, nor
         is it required.
         FreeBSD &release.5x; uses a device filesystem, which automatically
         creates device nodes on demand.  For more information,
         please see &man.devfs.5;.</para>

      <para>UFS2 is the default on-disk format for file systems
	created using &man.newfs.8;.  For all platforms except pc98,
	it is also the default for file systems created using the disk
	labeling screen within &man.sysinstall.8;.  Because &os;
	&release.4x; only understands UFS1 (not UFS2), disk partitions
	that need to be accessed by both &release.5x; and &release.4x;
	must be created with UFS1.  This can be specified using the
	<option>-O1</option> option to &man.newfs.8;, or on the disk
	labeling screen in &man.sysinstall.8;.  This situation most
	often arises with a a single machine that dual-boots &os;
	&release.4x; and &os; &release.5x;.  Note that there is no way
	to convert file systems between the two on-disk formats (other
	than backing up, re-creating the file system, and
	restoring).</para>

    </sect2>
  </sect1>

  <sect1 id="summary">

    <title>Summary</title>

    <para>While &os; &release.current; 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 &release.5x;
      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>

  </sect1>
</article>