d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Retire the Early Adopter's Guide in HEAD.

Browse Source
This commit is contained in:
Hiroki Sato 2005-03-09 18:32:29 +00:00
parent d8a46c80db
commit 142cd93898
3 changed files with 0 additions and 563 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
release/doc/en_US.ISO8859-1/Makefile
View File

@ -7,7 +7,6 @@ SUBDIR+= hardware
SUBDIR+= readme
SUBDIR+= errata
SUBDIR+= installation
#SUBDIR+= early-adopter
COMPAT_SYMLINK = en

18
release/doc/en_US.ISO8859-1/early-adopter/Makefile
View File

@ -1,18 +0,0 @@
# $FreeBSD$
RELN_ROOT?= ${.CURDIR}/../..
.ifdef NO_LANGCODE_IN_DESTDIR
DESTDIR?= ${DOCDIR}/early-adopter
.else
DESTDIR?= ${DOCDIR}/en_US.ISO8859-1/early-adopter
.endif
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS+= article.sgml
.include "${RELN_ROOT}/share/mk/doc.relnotes.mk"
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

544
release/doc/en_US.ISO8859-1/early-adopter/article.sgml
View File

@ -1,544 +0,0 @@
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
<!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN">
%release;
<!ENTITY release.4x "4.<replaceable>X</replaceable>">
<!ENTITY release.5x "5.<replaceable>X</replaceable>">
<!ENTITY release.4last "4.10-RELEASE">
<!ENTITY release.5branchpoint "5.3-RELEASE">
]>
<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>
<year>2004</year>
<holder role="mailto:re@FreeBSD.org">The &os; Release
Engineering Team</holder>
</copyright>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.microsoft;
&tm-attrib.sparc;
&tm-attrib.general;
</legalnotice>
<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
&release.4last;) 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 &release.5branchpoint;.</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, 5.1, and 5.2 are based on the CURRENT branch. The
first of these releases was made after over two years of development
(prior to these, the
last release from HEAD 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 around the time of
&release.5branchpoint;.</para>
<para>More information on &os; release engineering processes can be found
on the <ulink
url="&url.base;/releng/index.html">Release
Engineering Web pages</ulink> and in the <ulink
url="&url.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="&url.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).
Ongoing work aims to perform fine-grained locking of various
kernel subsystems to increase the number of threads of
execution that can be running in the kernel. More
information can be found on the
<ulink url="&url.base;/smp/index.html">FreeBSD SMP
Project</ulink> page.</para>
</listitem>
<listitem>
<para>KSE: Kernel Scheduled Entities allow a single process
to have multiple kernel-level threads, similar to Scheduler
Activations. The <filename>libkse</filename>
and <filename>libthr</filename> threading libraries make this
feature available to multi-threaded userland programs,
using the &man.pthread.3; API.</para>
</listitem>
<listitem>
<para>New architectures: Support for the sparc64, ia64, and amd64
architectures, in addition to the i386, pc98, and
alpha.</para>
</listitem>
<listitem>
<para>GCC: The compiler toolchain is now based on GCC
3.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. The GBDE 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>
<listitem>
<para>Bluetooth: Support for Bluetooth devices.</para>
</listitem>
</itemizedlist>
<para>A more comprehensive list of new features can be found in
the release notes for the various &os; &release.5x; releases.</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, particularly on newer machine
architectures. In some (hopefully rare) cases,
user-visible structures may change, requiring recompiling of
applications or reinstallation of ports/packages.</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; &release.5x;, whereas they did under &os;
4-STABLE. Generally these problems are caused by compiler
toolchain changes or cleanups of header files. In some
cases they are caused by changes in kernel or device
support.</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, and it may be difficult to gauge their effects on
stability and performance.</para>
</listitem>
<listitem>
<para>A certain amount of debugging and diagnostic code is
still in place to help track down problems in &os; &release.5x;'s new
features. This may cause &os; &release.5x; 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; &release.5x; does not have the stabilizing influence of a
-STABLE branch. (It is likely that the 5-STABLE development
branch will be created sometime after
&release.5branchpoint;.)</para>
</listitem>
<listitem>
<para>Documentation (such as the &os; <ulink
url="&url.books.handbook;/index.html">Handbook</ulink>
and <ulink
url="&url.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. While we believe that
many initial problems with stability have been fixed, some
issues with performance are still being addressed by
works-in-progress. We also note that best common practices in
system administration call for trying operating system upgrades
in a test environment before upgrading one's production, or
<quote>mission-critical</quote> systems.</para>
</sect1>
<sect1 id="plans-stable">
<title>Plans for the 4-STABLE Branch</title>
<para>It is important to note that even though releases are being
made in the &release.5x; series, support for &release.4x;
releases will continue for some time.
Indeed, &os; 4.8 was released two months after
5.0, in April 2003, followed by 4.9, in October 2003,
and 4.10 in May 2004.
Future releases from the 4-STABLE branch (if any) 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). We note that in general, the &os; community
(both users and developers) has shown a preference for
moving forward with new features in
the &release.5x; branch and beyond, due to the difficulty
involved in backporting (and maintaining) new functionality in
&release.4x;.</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="&url.base;/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>
<para>At this point, the release engineering team has no specific
plans for future releases from the 4-STABLE development branch,
and we decided to maintain 4.10-RELEASE as <quote>Errata Branch</quote>.
Previously a branch where a release is made has been maintained
as <quote>Security Branch</quote> by the &a.security-officer;
for a certain period, and they would only have critical
security fixes applied. With FreeBSD 4.10-RELEASE
the scope of fixes will be expanded to include local
Denial of Service fixes as well as other significant
and well-tested fixes that may not represent security issues.
While those fixes will not likely to be published
as a <quote>release</quote> from the branch,
the &os; Errata Notice will cover them in the same manner
as the &os; Security Advisory.</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. Examples of these files
include old C++ headers, programs moved to the Ports
Collection, or shared libraries that have moved to support
dynamically-linked root filesystem executables.</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;
&release.5x;, 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; &windowsnt;
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.
Using old ports may be possible in some cases, although there
are a number of known cases of backward incompatibility. As an
example, the
<filename role="package">devel/gnomevfs2</filename>,
<filename role="package">mail/postfix</filename>, and
<filename role="package">security/cfs</filename> ports need to
be recompiled due to changes in the <literal>statfs</literal>
structure.</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>