path: root/en_US.ISO8859-1/books/dev-model/book.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
	"../../../share/xml/freebsd45.dtd" [
<!ENTITY % chapters SYSTEM "chapters.ent">
%chapters;
]>

<!--
  - Copyright (c) 2002-2005 Niklas Saers
  - All rights reserved.
  -
  - Redistribution and use in source and binary forms, with or without
  - modification, are permitted provided that the following conditions
  - are met:
  - 1. Redistributions of source code must retain the above copyright
  - notice, this list of conditions and the following disclaimer.
  - 2. Redistributions in binary form must reproduce the above copyright
  - notice, this list of conditions and the following disclaimer in the
  - documentation and/or other materials provided with the distribution.
  -
  - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  - ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  - SUCH DAMAGE.
  -
  - $FreeBSD$
  -->

<book lang='en'>
     <bookinfo>
        <title>A project model for the FreeBSD Project</title>
        <author>
            <firstname>Niklas</firstname>
            <surname>Saers</surname>
        </author>
        <copyright>
            <year>2002-2005</year>
            <holder>Niklas Saers</holder>
        </copyright>
	<revhistory>
	  <revision>
	      <revnumber>1.3</revnumber>
	      <date>October, 2012</date>
	      <revremark>Remove hats held by specific people, these
		are documented elsewhere.</revremark>
	    </revision>
            <revision>
                <revnumber>1.2</revnumber>
                <date>April, 2005</date>
                <revremark>Update one year of changes, replace statistics with those of 2004</revremark>
            </revision>
            <revision>
                <revnumber>1.1</revnumber>
                <date>July, 2004</date>
                <revremark>First update within the FreeBSD tree</revremark>
            </revision>
            <revision>
                <revnumber>1.0</revnumber>
                <date>December 4th, 2003</date>
                <revremark>Ready for commit to FreeBSD Documentation</revremark>
            </revision>
            <revision>
                <revnumber>0.7</revnumber>
                <date>April 7th, 2003</date>
                <revremark>Release for review by the Documentation team</revremark>
            </revision>
            <revision>
                <revnumber>0.6</revnumber>
                <date>March 1st, 2003</date>
                <revremark>Incorporated corrections noted by
                interviewees and reviewers</revremark>
            </revision>
            <revision>
                <revnumber>0.5</revnumber>
                <date>February 1st, 2003</date>
                <revremark>Initial review by interviewees</revremark>
            </revision>
        </revhistory>

	<releaseinfo>$FreeBSD$</releaseinfo>
    </bookinfo>
    <preface id="foreword">

        <title>Foreword</title>
        <para>
            Up until now, the FreeBSD project has released a number of
            described techniques to do different parts of work. However,
            a project model summarising how the project is structured is needed
            because of the increasing amount of project members.
            <footnote>
                <para>
                    This goes hand-in-hand with Brooks' law that <quote>adding
                    another person to a late project will make it later</quote>
                    since it will increase the communication needs <xref linkend="brooks"/>.
                    A project model
                    is a tool to reduce the communication needs.
                </para>
            </footnote>
            This paper
            will provide such a project model and is donated to the
            FreeBSD Documentation project where it can evolve together with
            the project so that it can at any point in time reflect the way
            the project works. It is based on <citation><xref linkend="thesis"/></citation>.
        </para>

        <para>
            I would like to thank the following people for taking the time
            to explain things that were unclear to me and for proofreading
            the document.</para>
            <itemizedlist>
                <listitem><para>Andrey A. Chernov <email>ache@freebsd.org</email></para></listitem>
                <listitem><para>Bruce A. Mah <email>bmah@freebsd.org</email></para></listitem>
                <listitem><para>Dag-Erling Sm&oslash;rgrav <email>des@freebsd.org</email></para></listitem>
                <listitem><para>Giorgos Keramidas<email>keramida@freebsd.org</email></para></listitem>
                <listitem><para>Ingvil Hovig <email>ingvil.hovig@skatteetaten.no</email></para></listitem>
                <listitem><para>Jesper Holck<email>jeh.inf@cbs.dk</email></para></listitem>
                <listitem><para>John Baldwin <email>jhb@freebsd.org</email></para></listitem>
                <listitem><para>John Polstra <email>jdp@freebsd.org</email></para></listitem>
                <listitem><para>Kirk McKusick <email>mckusick@freebsd.org</email></para></listitem>
                <listitem><para>Mark Linimon <email>linimon@freebsd.org</email></para></listitem>
                <listitem><para>Marleen Devos</para></listitem>
                <listitem><para>Niels J&oslash;rgenssen<email>nielsj@ruc.dk</email></para></listitem>
                <listitem><para>Nik Clayton <email>nik@freebsd.org</email></para></listitem>
                <listitem><para>Poul-Henning Kamp <email>phk@freebsd.org</email></para></listitem>
                <listitem><para>Simon L. Nielsen <email>simon@freebsd.org</email></para></listitem>
            </itemizedlist>

    </preface>

    <chapter id="overview">
        <title>Overview</title>


        <para>
            A project model is a means to reduce the communications overhead in
            a project. As shown by <citation><xref linkend="brooks"/></citation>, increasing the
            number of project participants increases the communication in the
            project exponentionally. FreeBSD has during the past few years
            increased both its mass of active users and committers, and the
            communication in the project has risen accordingly. This project
            model will serve to reduce this overhead by providing an up-to-date
            description of the project.
        </para>

        <para>
            During the Core elections in 2002, Mark Murray stated
            <quote>I am opposed to a long rule-book, as that satisfies
	           lawyer-tendencies, and is counter to the technocentricity that
		   the project so badly needs.</quote>

            <citation><xref linkend="bsd-election2002"/></citation>.
            This project model is not meant to be a tool to
            justify creating impositions for developers, but as a tool to
            facilitate coordination.
            It is meant as a
            description of the project, with an overview of how the different
            processes are executed.
            It is an introduction to how the FreeBSD
            project works.

        </para>

        <para>
            The FreeBSD project model will be described as of
            July 1st, 2004. It is based on the Niels J&oslash;rgensen's paper
            <citation><xref linkend="jorgensen2001"/></citation>,
            FreeBSD's official documents,
            discussions on FreeBSD mailing lists and interviews with
            developers.
        </para>

        <para>
            After providing definitions of terms used, this document will outline
            the organisational structure (including role descriptions and
            communication lines),
            discuss the methodology model and after presenting the
            tools used for process control, it will present the defined
            processes. Finally it will outline major sub-projects of the
            FreeBSD project.
        </para>

        <para>
            <citation><xref
            linkend="freebsd-developer-handbook"/>, Section 1.2 and 1.3</citation>
            give the vision and the architectural guidelines for the
            project. The vision is <quote>To produce the best UNIX-like
                operating system package possible, with due respect to the
                original software tools ideology as well as usability,
            performance and stability.</quote> The architectural
            guidelines help determine whether a problem that someone wants
            to be solved is within the scope of the project
        </para>
</chapter>

        <chapter id="definitions">
            <title>Definitions</title>

            <section id="ref-activity" xreflabel="">
                <title>Activity</title>

                <para>
                    An <quote>activity</quote> is an element of work performed
                    during the course of a project <citation><xref linkend="ref-pmbok"/></citation>.
                    It has an output and
                    leads towards an outcome.
                    Such an output can either be an input to another
                    activity or a part of the process' delivery.
                </para>


            </section>

            <section id="def-process" xreflabel="">
                <title>Process</title>

                <para>
                    A <quote>process</quote> is a series of activities
                    that lead towards a particular outcome. A process can
                    consist of one or more sub-processes. An example of a process is software
                    design.
                </para>

            </section>

            <section id="ref-hat" xreflabel="Hat">
                <title>Hat</title>

                <para>
                    A <quote>hat</quote> is synonymous with role. A hat has
                    certain responsibilities in a process and for the process
                    outcome. The hat executes activities. It is well defined what
                    issues the hat should be contacted about by the project
                    members and people outside the project.
                </para>

            </section>

            <section id="ref-outcome" xreflabel="Outcome">
                <title>Outcome</title>

                <para>
                    An <quote>outcome</quote> is the final output of the process.
                    This is synonymous with deliverable, that is defined as
                    <quote>any measurable, tangible, verifiable outcome, result or
                        item that must be produced to complete a project or part of a
                        project. Often used more narrowly in reference to an external
                        deliverable, which is a deliverable that is subject to approval
                    by the project sponsor or customer</quote> by <citation><xref
                    linkend="ref-pmbok"/></citation>.
                    Examples of
                    outcomes are a piece of software, a decision made or a
                    report written.
                </para>

            </section>


            <section id="ref-freebsd" xreflabel="">
                <title>FreeBSD</title>

                <para>
                    When saying <quote>FreeBSD</quote> we will mean the BSD
                    derivative UNIX-like operating system
                    FreeBSD, whereas when saying <quote>the FreeBSD
                    Project</quote> we will mean the project organisation.
                </para>
            </section>
        </chapter>

        <chapter id="model-orgstruct">
            <title>Organisational structure</title>

            <para>
                While no-one takes ownership of FreeBSD, the FreeBSD
                organisation is divided into core, committers and contributors
                and is part of the FreeBSD community that lives around it.

            </para>
            <para>
                <figure>
                    <title>The FreeBSD Project's structure</title>
                    <graphic fileref="orghierarchy"/>
                </figure>
            </para>

            <para>
                Number of committers has been determined by going through
                CVS logs from January 1st, 2004 to December 31st, 2004 and
                contributors by going through the list of contributions and
                problem reports.
            </para>

            <para>
                The main resource in the FreeBSD community is its developers: the
                committers and contributors. It is with their contributions that the
                project can move forward. Regular developers are referred to as contributors.
                As by January 1st, 2003, there are an estimated 5500
                contributors on the project.
		<!--
		  Contributors = people submitting PRs + people submitting code - overlap.
		  Lost the script, TODO: recompute the estimate
		-->

            </para>

            <para>
                Committers are developers with the privilege of being able to
                commit changes. These are usually the
                most active developers who are willing to
                spend their time not only integrating their own code but
                integrating code submitted by the developers who
                do not have this privilege. They are also the developers who elect
                the core team, and they have access to closed discussions.
            </para>

            <para>
	        <!-- 96 developers commit in one part only,
		     91 developers commit in two parts,
		     48 developers commit in three parts,
		     29 developers commit in all parts
		         Data from the entire year 2004 -->

                The project can be grouped into four distinct separate parts,
                and most developers will focus their involvement in one
		part of FreeBSD. <!-- 91.3% had 50% or more of their commits
		in one part during 2004 -->

		The four parts
                are kernel development, userland development, ports and
                documentation. When referring to the base system, both
                kernel and userland is meant.
            </para>

            <para>
                This split changes our triangle to look like this:
            </para>
            <para>
                <figure>
                    <title>The FreeBSD Project's structure with committers in categories</title>
                    <graphic fileref="orghierarchy2"/>
                </figure>
            </para>
            <para>
                Number of committers per area has been determined by going through
                CVS logs from January 1st, 2004 to December 31st, 2004.
                Note that many committers work in multiple
                areas, making the total number higher than the real number
                of committers. The total number of committers at that
                time was 269. <!-- Down from 275 in 2001 -->
            </para>

            <para>
                Committers fall into three
                groups: committers who are only concerned with one area of
                the project (for instance file systems), committers who
                are involved only with one sub-project
                and committers who commit to different parts
                of the code, including sub-projects.
                Because some committers work on different parts, the total
                number in the committers section of the triangle is higher than
                in the above triangle.
            </para>

            <para>
                The kernel is the main building block of FreeBSD. While
                the userland applications are protected against faults in
                other userland applications, the entire system is
                vulnerable to errors in the kernel. This, combined with the
                vast amount of dependencies in the kernel and that it is not easy to
                see all the consequences of a kernel change, demands
                developers with a relative full understanding of the
                kernel. Multiple development efforts in the kernel also
                requires a closer coordination than userland applications do.
            </para>

            <para>
                The core utilities, known as userland, provide the interface that identifies
                FreeBSD, both user interface, shared libraries and external interfaces to
                connecting clients. Currently, 162 people are involved in userland
                development and maintenance, many being maintainers for
                their own part of the code.
                Maintainership will
                be discussed in the <xref linkend="role-maintainer"/> section.
            </para>

            <para>
                Documentation is handled by <xref linkend="sub-project-documentation"/>
                and includes all documents surrounding the
                FreeBSD project, including the web pages. There were during 2004 101
		people making commits to the FreeBSD Documentation Project.
            </para>

            <para>
                Ports is the collection of meta-data that is needed to make
                software packages build correctly on FreeBSD. An example of a port
                is the port for the web-browser Mozilla. It contains
                information about where to fetch the source, what patches to
                apply and how, and how the package should be installed on the
                system. This allows automated tools to fetch, build and
                install the package. As of this writing, there are more than
                12600 ports available.
                <footnote>
                    <para>
                        Statistics are generated by counting the number of
                        entries in the file fetched by portsdb by April 1st, 2005.
			portsdb is a part of the port sysutils/portupgrade.
                    </para>
                </footnote>
                , ranging
                from web servers to games, programming languages and most of the
                application types that are in use on modern computers.

                Ports will be discussed further in the section
                <xref linkend="sub-project-ports"/>.

            </para>

        </chapter>

        <chapter id="methodology-model">
            <title>Methodology model</title>

            <section id="development-model"><title>Development model</title>

                <para>
                    There is no defined model for how people write code in
                    FreeBSD. However, Niels J&oslash;rgenssen has suggested a model of
                    how written code is integrated into the project.
                </para>

                <para>
                    <figure>
                        <title>J&oslash;rgenssen's model for change integration</title>
                        <graphic fileref="maintenance"/>
                    </figure>
                </para>

                <para>
                    The <quote>development release</quote> is the FreeBSD-CURRENT
                    ("-CURRENT") branch and the <quote>production release</quote>
                    is the FreeBSD-STABLE branch ("-STABLE")
                    <citation><xref linkend="jorgensen2001"/></citation>.
                </para>

                <para>
                    This is a model for one change, and shows that after
                    coding, developers seek community review and
                    try integrating it with their own systems. After integrating the change
                    into the development release, called FreeBSD-CURRENT, it is tested
                    by many users and developers in the FreeBSD community. After it
                    has gone through enough testing, it is merged into the production
                    release, called FreeBSD-STABLE. Unless each stage is finished
                    successfully, the developer needs to go back and make
                    modifications in the code and restart the process. To integrate a
                    change with either -CURRENT or -STABLE is called making a commit.
                </para>

                <para>
                    J&oslash;rgensen found that most FreeBSD developers work
                    individually, meaning that this model is used in parallel by
                    many developers on the different ongoing development efforts. A
                    developer can also be working on multiple changes, so that while
                    he is waiting for review or people to test one or more of his
                    changes, he may be writing another change.
                </para>

                <para>
                    As each commit represents an increment, this is a massively
                    incremental model. The commits are in fact so frequent that
                    during one year
                    <footnote>
                        <para>
                            The period from January 1st, 2004 to December 31st, 2004 was
                            examined to find this number.
                        </para>
                    </footnote>
                    , 85427 commits were made, making a daily average of 233
                    commits.
                </para>

                <para>
                    Within the <quote>code</quote> bracket in J&oslash;rgensen's
                    figure, each programmer has his own working style and follows his
                    own development models. The bracket could very well have been
                    called <quote>development</quote> as it includes requirements
                    gathering and analysis, system and detailed design,
                    implementation and verification. However, the only
                    output from these stages is the source code or system documentation.
                </para>


                <para>
                    From a stepwise model's perspective (such as the waterfall
                    model), the other brackets can be seen as further verification
                    and system integration. This system integration is also important
                    to see if a change is accepted by the community. Up until the
                    code is committed, the developer is free to choose how much to
                    communicate about it to the rest of the project. In order for
                    -CURRENT to work as a buffer (so that bright ideas that had some
                    undiscovered drawbacks can be backed out) the minimum time a
                    commit should be in -CURRENT before merging it to -STABLE is 3
                    days. Such a merge is referred to as an MFC (Merge From Current).
                </para>

                <para>
                    It is important to notice the word <quote>change</quote>. Most
                    commits do not contain radical new features, but are maintenance
                    updates.
                </para>

                <para>
                    The only exceptions from this model are security fixes and
                    changes to features that are deprecated in the -CURRENT branch.
                    In these cases, changes can be committed directly to the -STABLE branch.
                </para>

                <para>
                    In addition to many people working on the project, there are
                    many related projects to the FreeBSD Project. These are either
                    projects developing brand new features,
                    sub-projects or projects whose outcome is incorporated into
                    FreeBSD
                    <footnote>
                        <para>
                            For instance, the development of the Bluetooth stack started
                            as a sub-project until it was deemed stable enough to be
                            merged into the -CURRENT branch. Now it is a part of the core
                            FreeBSD system.
                        </para>
                    </footnote>.
                    These projects fit into the FreeBSD Project just like regular
                    development efforts: they produce code that is integrated with
                    the FreeBSD Project. However, some of them (like Ports and
                    Documentation) have the privilege of being applicable to both
                    branches or commit directly to both -CURRENT and -STABLE.
                </para>

                <para>
                    There is no standards to how design should be done, nor is
                    design collected in a centralised repository.
                    The main design is that of 4.4BSD.
                    <footnote>
                        <para>
                            According to Kirk McKusick, after 20 years of developing
                            UNIX operating systems, the interfaces are for the most part
                            figured out. There is therefore no need for much
                            design. However, new applications of the system and new hardware leads to
                            some implementations being more beneficial than those that
                            used to be preferred. One example is the introduction of web
                            browsing that made the normal TCP/IP connection a short
                            burst of data rather than a steady stream over a longer
                            period of time.
                        </para>
                    </footnote>

                    As design is a part of the <quote>Code</quote> bracket in
                    J&oslash;rgenssen's model, it is up to every developer or
                    sub-project how this should be done.


                    Even if the design should be stored in a central repository,
                    the output from the design stages would be of limited use as
                    the differences of methodologies would make them poorly if at
                    all interoperable. For the overall design of the project, the
                    project relies on the sub-projects to negotiate fit interfaces
                    between each other rather than to dictate interfacing.
                </para>

            </section>

            <section id="release-branches">
                <title>Release branches</title>

                <para>
                    The releases of FreeBSD is best illustrated by a tree with many
                    branches where each major branch represents a major
                    version. Minor versions are represented by branches of the
                    major branches.
                </para>

                <para>
                    In the following release tree, arrows that follow one-another
                    in a particular direction
                    represent a branch. Boxes with full lines and diamonds represent official
                    releases. Boxes with dotted lines represent the development
                    branch at that time. Security branches are represented by ovals.
                    Diamonds differ from boxes in that they
                    represent a fork, meaning a place where a branch splits into two
                    branches where one of the branches becomes a sub-branch.
                    For example,
                    at 4.0-RELEASE the 4.0-CURRENT branch split into 4-STABLE and
                    5.0-CURRENT. At 4.5-RELEASE, the branch forked off a security
                    branch called RELENG_4_5.
                </para>

                <para>
                    <figure>
                        <title>The FreeBSD release tree</title>
                        <graphic fileref="branches"/>
                    </figure>
                </para>
                <para>
                    The latest -CURRENT version
                    is always referred to as -CURRENT, while the latest -STABLE
                    release is always referred to as -STABLE. In this figure,
                    -STABLE refers to 4-STABLE while -CURRENT refers to
                    5.0-CURRENT following 5.0-RELEASE.
                    <citation><xref linkend="freebsd-releng"/></citation>
                </para>

                <para>
                    A <quote>major release</quote> is always made from the -CURRENT branch.
                    However, the -CURRENT branch does not need to fork at that point in time,
                    but can focus on stabilising. An example of this is that following
                    3.0-RELEASE, 3.1-RELEASE was also a continuation of the
                    -CURRENT-branch, and -CURRENT did not become a true development
                    branch until this version was released and the 3-STABLE branch
                    was forked. When
                    -CURRENT returns to becoming a development branch, it can only be
                    followed by a major release. 5-STABLE is predicted to be forked
                    off 5.0-CURRENT at around 5.3-RELEASE. It is not until
                    5-STABLE is forked that the development branch will be branded 6.0-CURRENT.
                </para>

                <para>
                    A <quote>minor release</quote> is made from the -CURRENT branch
                    following a major release, or from the -STABLE branch.
                </para>

                <para>
                    Following and including, 4.3-RELEASE<footnote>
                        <para>
                            The first release this actually happened for was 4.5-RELEASE,
                            but security branches were at the same time created for
                            4.3-RELEASE and 4.4-RELEASE.
                        </para>
                    </footnote>, when a minor release has been made, it becomes a <quote>security
                    branch</quote>. This is meant for organisations that do not want
                    to follow the -STABLE branch and the potential new/changed features it
                    offers, but instead require an absolutely stable environment, only
                    updating to implement security updates.
                    <footnote>
                        <para>
                            There is a terminology
                            overlap with respect to the word "stable", which leads to some
                            confusion. The -STABLE branch is still a
                            development branch, whose goal is to be
                            useful for most people.
                            If it is never acceptable for a system to get changes that
                            are not announced at the time it is deployed,
                            that system should run a security branch.
                        </para>
                    </footnote>
                </para>

                <para>
                    Each update to a security branch
                    is called a <quote>patchlevel</quote>. For every security
                    enhancement that is done, the patchlevel number is increased,
                    making it easy for people tracking the branch to see what
                    security enhancements they have implemented. In cases where there
                    have been especially serious security flaws, an entire new release
                    can be made from a security branch. An example of this is
                    4.6.2-RELEASE.
                </para>

            </section>

            <section id="model-summary">
                <title>Model summary</title>

                <para>
                    To summarise, the development model of FreeBSD can be seen as
                    the following tree:
                </para>

                <para>
                    <figure>
                        <title>The overall development model</title>
                        <graphic fileref="freebsd-code-model"/>
                    </figure>
                </para>
                <para>
                    The tree of the FreeBSD development with ongoing development
                    efforts and continuous integration.
                </para>


                <para>
                    The tree symbolises the release versions with major versions
                    spawning new main branches and minor versions being versions of
                    the main branch. The top branch is the -CURRENT branch where all
                    new development is integrated, and the -STABLE branch is the
                    branch directly below it.
                </para>

                <para>
                    Clouds of development efforts hang over the project
                    where developers use the development models they see fit. The
                    product of their work is then integrated into -CURRENT where it
                    undergoes parallel debugging and is finally merged from -CURRENT into
                    -STABLE. Security fixes are merged from -STABLE to the security branches.
                </para>

            </section>

        </chapter>

        <chapter id="sect-hats">
            <title>Hats</title>

            <para>
                Many committers have a special area of responsibility. These
                roles are called hats.
                These hats can
                be either project roles, such as public relations officer, or
                maintainer for a certain area of the
                code. Because this is a project where people give voluntarily of
                their spare time, people with assigned hats are not always
                available. They must therefore appoint a deputy that can perform
                the hat's role in his or her absence. The other option is to have
                the role held by a group.
            </para>

            <para>
                Many of these hats are not formalised. Formalised hats have a
                charter stating the exact purpose of the hat along with its
                privileges and responsibilities. The writing of such charters is
                a new part of the project, and has thus yet to be completed for
                all hats. These hat descriptions are not such a formalisation,
                rather a summary of the role with links to the charter where
                available and contact addresses.

            </para>


            <section id="general-hats">
                <title>General Hats</title>

                <section id="role-contributor" xreflabel="Contributor">
                    <title>Contributor</title>
                    <para>
                        A Contributor contributes to the FreeBSD project either as a
                        developer, as an author, by sending problem reports, or in
                        other ways contributing to the progress of the project. A
                        contributor has no special privileges in the FreeBSD project.
                        <citation><xref linkend="freebsd-contributors"/></citation>
                    </para>
                </section>

                <section id="role-committer" xreflabel="Committer">
                    <title>Committer</title>
                    <para>
                        A person who has the required privileges to add his code or documentation to the
                        repository.
                        <!--
                        Note that there are people with commit privileges that used
                        to be committers but have not done any commits the last
                        twelve months. These are not referred to as committers. -->

                        A committer has made a commit within the past 12 months.
                        <citation><xref linkend="freebsd-bylaws"/></citation>
                        An active committer is a committer
                        who has made an average of one commit per month during that time.
                    </para>

                    <para>
                        It is worth noting that there are no technical barriers to prevent
                        someone, once having gained commit privileges to the main- or a sub-project, to make commits in
                        parts of that project's source the committer did not specifically get
                        permission to modify. However, when wanting to make
                        modifications to parts a committer has not been involved in
                        before, he/she should read the logs to see what has happened
                        in this area before, and also read the MAINTAINER file to see if
                        the maintainer of this part has any special requests on how
                        changes in the code should be made
                        <!--
                        Also, since
                        <xref linkend="sub-project-ports"/> is allowed to give commit
                        privileges without approval from core, a committer who has
                        gained his privileges through contributing to the ports
                        sub-project should be careful and
                        have his changes approved before committing anything outside
                        the ports tree.
                        -->
                    </para>
                </section>

                <section id="role-core" xreflabel="Core team">
                    <title>Core Team</title>


                    <para>
                        The core team is elected by the committers from the pool of committers
                        and serves as the board of directors of the FreeBSD project. It
                        promotes active contributors to committers, assigns people to
                        well-defined hats, and is the final arbiter of decisions involving
                        which way the project should be heading.

                        As by July 1st, 2004, core consisted of 9 members.
                        Elections are held every two years.
                    </para>

                </section>

                <section id="role-maintainer" xreflabel="Maintainership">
                    <title>Maintainership</title>

                    <para>
                        Maintainership means that that person is responsible for
                        what is allowed to go into that area of the code and has the
                        final say should disagreements over the code occur. This
                        involves proactive work aimed at stimulating
                        contributions and reactive work in reviewing commits.
                    </para>

                    <para>
                        With the FreeBSD
                        source comes the MAINTAINERS file that contains a one-line
                        summary of how each maintainer would like contributions to be
                        made. Having this notice and contact information
                        enables developers to focus on the development effort rather
                        than being stuck in a slow correspondence should the maintainer
                        be unavailable for some time.
                    </para>

                    <para>
                        If the maintainer is unavailable for an unreasonably long period
                        of time, and other people do a significant amount of work,
                        maintainership may be switched without the maintainer's approval.
                        This is based on the stance that maintainership should be
                        demonstrated, not declared.
                    </para>

                    <para>
                        Maintainership of a particular piece of code is a hat that
                        is not held as a group.
                    </para>



                </section>

            </section>

            <section id="official-hats">
                <title>Official Hats</title>

                <para>
                    The official hats in the FreeBSD Project are hats that are more
                    or less formalised and mainly administrative roles. They have
                    the authority and responsibility for their area. The following
                    illustration shows the responsibility lines. After this follows
                    a description of each hat, including who it is held by.
                </para>

                <para>
                    <figure>
                        <title>Overview of official hats</title>
                        <graphic fileref="hats-overview"/>
                    </figure>
                </para>

                <para>
                    All boxes consist of groups of committers, except for the
                    dotted boxes where the holders are not necessarily committers. The
                    flattened circles are sub-projects and consist of both
                    committers and non-committers of the main project.
                </para>



                <section id="role-doc-manager" xreflabel="Documentation
                    project architect">
                    <title>Documentation project manager</title>
                    <para>
                        <xref linkend="sub-project-documentation"/>
                        architect is responsible for
                        defining and following up documentation goals for the
                        committers in the Documentation project.
                    </para>

                    <para>
                        Hat held by:
                        The DocEng team <email>doceng@FreeBSD.org</email>.
                        The
                        <ulink url="http://www.freebsd.org/internal/doceng.html">
                        DocEng Charter</ulink>.
                    </para>
                </section>

                <section id="role-cvsup-coordinator" xreflabel="CVSup Mirror Site Coordinator">
                    <title>CVSup Mirror Site Coordinator</title>
                    <para>
                        The CVSup Mirror Site Coordinator coordinates all the
                        <xref linkend="role-cvsup-sitemaint"/>s to ensure that they
                        are distributing current versions of the software, that they
                        have the capacity to update themselves when major updates
                        are in progress, and making it easy for the general public
                        to find their closest CVSup mirror.
                    </para>
                    <para>
                        Hat currently held by:
                        The CVSup-master team <email>cvsup-master@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-postmaster" xreflabel="Postmaster">
                    <title>Postmaster</title>
                    <para>
                        The Postmaster is responsible for mail being correctly
                        delivered to the committers' email address. He is also
                        responsible for ensuring that the mailing lists work and
                        should take measures against possible disruptions of mail
                        such as having troll-, spam- and virus-filters.
                    </para>
                    <para>
                        Hat currently held by:
                        the Postmaster Team <email>postmaster@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-release-coordination" xreflabel="Release Coordination">
                    <title>Release Coordination</title>

                    <para>
                        The responsibilities of the Release Engineering Team are
                        <itemizedlist>
                            <listitem><para>
                                    Setting, publishing and following a release schedule for
                                    official releases
                            </para></listitem>
                            <listitem><para>
                                    Documenting and formalising release engineering procedures
                            </para></listitem>
                            <listitem><para>
                                    Creation and maintenance of code branches
                            </para></listitem>
                            <listitem><para>
                                    Coordinating with the Ports and Documentation teams
                                    to have an updated set of packages and documentation
                                    released with the new releases
                            </para></listitem>
                            <listitem><para>
                                    Coordinating with the Security team so that pending
                                    releases are not affected by recently disclosed vulnerabilities.
                            </para></listitem>
                        </itemizedlist>

                        Further information about the development process is
                        available in the <xref linkend="process-release-engineering"/> section.
                    </para>

                    <para id="role-releng" xreflabel="Release Engineering Team">
                        Hat held by:
                        the Release Engineering team <email>re@FreeBSD.org</email>.
                        The
                        <ulink url="http://www.freebsd.org/releng/charter.html">
                        Release Engineering Charter</ulink>.
                    </para>
                </section>

                <section id="role-pr-cr" xreflabel="Public Relations &amp; Corporate Liaison">
                    <title>Public Relations &amp; Corporate Liaison</title>
                    <para>
                        The Public Relations &amp; Corporate Liaison's
                        responsibilities are:
                        <itemizedlist>
                            <listitem><para>
                                    Making press statements when happenings that are
                                    important to the FreeBSD Project happen.
                            </para></listitem>
                            <listitem><para>
                                    Being the official contact person for corporations that
                                    are working close with the FreeBSD Project.
                            </para></listitem>
                            <listitem><para>
                                    Take steps to promote FreeBSD within both the Open Source
                                    community and the corporate world.
                            </para></listitem>
                            <listitem><para>
                                    Handle the <quote>freebsd-advocacy</quote> mailing list.
                            </para></listitem>
                        </itemizedlist>
                    </para>

                    <para>
                        This hat is currently not occupied.
                    </para>
                </section>

                <section id="role-security-officer" xreflabel="Security Officer">
                    <title>Security Officer</title>
                    <para>
                        The Security Officer's main responsibility is to
                        coordinate information exchange with others in the
                        security community and in the FreeBSD project.

                        The Security Officer is also responsible for taking action
                        when security problems are reported and promoting proactive
                        development behaviour when it comes to security.
                    </para>
                    <para>
                        Because of the fear that information about
                        vulnerabilities may leak out to people with malicious
                        intent before a patch is available, only the Security
                        Officer, consisting of an officer, a deputy and two
                        <xref linkend="role-core"/> members, receive sensitive
                        information about security issues. However, to create or
                        implement a patch, the Security Officer has the Security
                        Officer Team <email>security-team@FreeBSD.org</email> to
                        help do the work.
                    </para>
                </section>

                <section id="role-repo-manager" xreflabel="Source Repository Manager">
                    <title>Source Repository Manager</title>
                    <para>
                        The Source Repository Manager is the only one who is allowed
                        to directly modify the repository without using the
                        <xref linkend="tool-svn"/> tool.
                        It is his/her
                        responsibility to ensure that technical problems that arise in the
                        repository are resolved quickly. The source repository
                        manager has the authority to back out commits if this is
                        necessary to resolve a CVS technical problem.
                    </para>
                    <para>
                        Hat held by:
			the Source Repository Manager <email>cvs@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-election-manager" xreflabel="Election Manager">
                    <title>Election Manager</title>
                    <para>
                        The Election Manager is responsible for the
                        <xref linkend="process-core-election"/> process. The manager
                        is responsible for running and maintaining the election
                        system, and is the final authority should minor unforeseen
                        events happen in the election process. Major unforeseen
                        events have to be discussed with the <xref linkend="role-core"/>
                    </para>
                    <para>
                        Hat held only during elections.
                    </para>
                </section>

                <section id="role-webmaster" xreflabel="Web site Management">
                    <title>Web site Management</title>
                    <para>
                        The Web site Management hat is responsible for coordinating
                        the rollout of updated web pages on mirrors around the world,
                        for the overall structure of the primary web site and the
                        system it is running upon. The management needs to
                        coordinate the content with
                        <xref linkend="sub-project-documentation"/> and acts as
                        maintainer for the <quote>www</quote> tree.

                    </para>
                    <para>
                        Hat held by:
                        the FreeBSD Webmasters <email>www@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-ports-manager" xreflabel="Ports Manager">
                    <title>Ports Manager</title>
                    <para>
                        The Ports Manager acts as a liaison between
                        <xref linkend="sub-project-ports"/>
                        and the core project, and
                        all requests from the project should go to the ports manager.

                    </para>

                    <para>
                        Hat held by:
                        the Ports Management Team <email>portmgr@FreeBSD.org</email>.
                        The
                        <ulink url="http://www.freebsd.org/portmgr/charter.html">
                            Portmgr charter</ulink>.
                    </para>
                </section>

                <section id="role-standards" xreflabel="Standards">
                    <title>Standards</title>
                    <para>
                        The Standards hat is responsible for ensuring that FreeBSD
                        complies with the standards it is committed to <!-- (covered in
                        <xref linkend="standardsguidelines"/>) -->, keeping up to date
                        on the development of these standards and notifying
                        FreeBSD developers of important changes that allows them to take a
                        proactive role and decrease the time between a standards
                        update and FreeBSD's compliancy.
                    </para>

                    <para>
                        Hat currently held by:
                        Garrett Wollman <email>wollman@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-core-secretary" xreflabel="Core Secretary">
                    <title>Core Secretary</title>
                    <para>
                        The Core Secretary's main responsibility is to write drafts to
                        and publish the final Core Reports. The secretary also keeps
                        the core agenda, thus ensuring that no balls are dropped
                        unresolved.
                    </para>
                    <para>
                        Hat currently held by: &a.pgj.email;.
                    </para>
                </section>

                <section id="role-gnats" xreflabel="GNATS Administrator">
                    <title>GNATS Administrator</title>
                    <para>
                        The GNATS Administrator is responsible for ensuring that the
                        maintenance database is in working order, that the entries
                        are correctly categorised and that there are no invalid entries.
                    </para>
                    <para>
                        Hat currently held by:
                        the Bugmeister Team <email>bugmeister@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-bugmeister" xreflabel="Bugmeister">
                    <title>Bugmeister</title>
                    <para>
                        The Bugmeister is the person in charge of the problem report
                        group.

                    </para>
                    <para>
                        Hat currently held by:
                        the Bugmeister Team <email>bugmeister@FreeBSD.org</email>,
                    </para>
                </section>

                <section id="role-donations" xreflabel="Donations Liaison Officer">
                    <title>Donations Liaison Officer</title>
                    <para>
                        The task of
                        the donations liaison officer is to match
                        the developers with needs with people or
                        organisations willing to make a
                        donation. The Donations Liaison Charter is
                        available
                        <ulink url="http://www.freebsd.org/donations/">here</ulink>
                    </para>
                    <para>
                        Hat held by:
                        the Donations Liaison Office <email>donations@FreeBSD.org</email>.
                    </para>
                </section>

                <section id="role-admin" xreflabel="Admin">
                    <title>Admin</title>
                    <para>
                        (Also called <quote>FreeBSD Cluster Admin</quote>)
                    </para>

                    <para>
                        The admin team consists of the
                        people responsible for administrating the
                        computers that the project relies on for
                        its distributed work and communication to
                        be synchronised. It consists mainly of those
                        people who have physical access to the
                        servers.
                    </para>

                    <para>
                        Hat held by:
                        the Admin team <email>admin@FreeBSD.org</email>.
                    </para>

                </section>



            </section>

            <section id="proc-depend-hats">
                <title>Process dependent hats</title>

                <section id="role-problem-originator" xreflabel="Report originator">
                    <title>Report originator</title>
                    <para>
                        The person originally responsible for
                        filing a Problem Report.
                    </para>
                </section>


                <section id="role-bugbuster" xreflabel="Bugbuster">
                    <title>Bugbuster</title>
                    <para>
                        A person who will either find the right
                        person to solve the problem, or close the PR if
                        it is a duplicate or otherwise
                        not an interesting one.
                    </para>
                </section>

                <section id="role-mentor" xreflabel="Mentor">
                    <title>Mentor</title>
                    <para>
                        A mentor is a committer who takes it upon him/her to
                        introduce a new committer to the project, both in terms of
                        ensuring the new committers setup is valid,
                        that the new committer knows the available tools required in
                        his/her work and that the
                        new committer knows what is expected of him/her in terms of
                        behaviour.
                    </para>
                </section>
                <section id="role-vendor" xreflabel="Vendor">
                    <title>Vendor</title>
                    <para>
                        The person(s) or organisation whom
                        external code comes from and whom patches are sent to.
                    </para>
                </section>

                <section id="role-reviewer" xreflabel="Reviewer">
                    <title>Reviewers</title>
                    <para>
                        People on the mailing list where the request
                        for review is posted.
                    </para>
                </section>

                <section id="role-cvsup-sitemaint" xreflabel="CVSup Mirror Site
                    Admin">
                    <title>CVSup Mirror Site Admin</title>
                    <para>
                        A CVSup Mirror Site Admin has accesses to a server that he/she
                        uses to mirror the CVS repository. The admin works with the
                        <xref linkend="role-cvsup-coordinator"/> to ensure the site
                        remains up-to-date and is following the general policy of
                        official mirror sites.
                    </para>
                </section>


            </section>


        </chapter>

        <chapter id="model-processes" xreflabel="processes">
            <title>Processes</title>

            <para>
                The following section will describe the defined project
                processes. Issues that are not handled by these processes happen
                on an ad-hoc basis based on what has been customary to do in
                similar cases.
            </para>

            <section id="proc-addrem-committer">
                <title>Adding new and removing old committers</title>

                <para>
                    The Core team has the responsibility of giving and removing
                    commit privileges to contributors. This can only be done
                    through a vote on the core mailing list.

                    The ports and documentation sub-projects can give commit
                    privileges to people working on these projects, but have to
                    date not removed such privileges. <!-- ref Bruce <bmah@> -->
                </para>

                <para>
                    Normally a contributor is recommended to core by a
                    committer. For contributors or outsiders to contact
                    core asking to be a committer is not well thought of
                    and is usually rejected.

                </para>

                <para>
                    If the area of particular interest for the developer
                    potentially overlaps with other committers' area of
                    maintainership, the opinion of those maintainers is
                    sought. However, it is frequently this committer that
                    recommends the developer.
                </para>

                <para>
                    When a contributor is given committer status, he is
                    assigned a mentor. The committer who recommended the
                    new committer will, in the general case, take it upon
                    himself to be the new committers mentor.

                </para>

                <para>
                    When a contributor is given his commit bit, a <xref linkend="tool-pgp"/>-signed email is sent
                    from either <xref linkend="role-core-secretary"/>,
                    <xref linkend="role-ports-manager"/> or nik@freebsd.org to both
                    admins@freebsd.org, the assigned mentor, the new committer and
                    core confirming the approval of a new account. The mentor then
                    gathers a password line, <xref linkend="tool-ssh2"/> public key and PGP key from the
                    new committer and sends them to <xref
                    linkend="role-admin"/>. When the new account is created, the
                    mentor activates the commit bit and guides the new committer
                    through the rest of the initial process.
                </para>

                <para>
                    <figure>
                        <title>Process summary: adding a new committer</title>
                        <graphic fileref="proc-add-committer"/>
                    </figure>
                </para>

                <para>
                    When a contributor sends a piece of code, the receiving
                    committer may choose to recommend that the contributor is
                    given commit privileges. If he recommends this to core,
                    they will vote on this recommendation. If they vote in
                    favour, a mentor is assigned the new committer and the new
                    committer has to email his details to the administrators
                    for an account to be created. After this, the new
                    committer is all set to make his first commit.  By
                    tradition, this is by adding his name to the committers list.
                </para>

                <para>
                    Recall that a committer is considered to be someone who
                    has committed code during the past 12
                    months. However, it is not until after 18 months of inactivity
                    have passed
                    that commit privileges are eligible to be revoked.
                    <citation><xref linkend="freebsd-expiration-policy"/></citation>
                    There are, however, no
                    automatic procedures for doing this.
                    For reactions concerning commit privileges not triggered by
                    time, see <link linkend="process-reactions">section 1.5.8</link>.
                </para>

                <para>
                    <figure>
                        <title>Process summary: removing a committer</title>
                        <graphic fileref="proc-rm-committer"/>
                    </figure>
                </para>

                <para>
                    When Core decides to clean up the committers list, they
                    check who has not made a commit for the past 18 months.
                    Committers who have not done so have their commit
                    bits revoked.
                </para>

                <para>
                    It is also possible for committers to request that their commit
                    bit be retired if for some reason they are no longer going
                    to be actively committing to the project.  In this case, it can also
                    be restored at a later time by core, should the committer ask.
                </para>

                <para>
                    Roles in this process:

                    <orderedlist>
                        <listitem><para>
                                <xref linkend="role-core"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-contributor"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-committer"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-maintainer"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-mentor"/>
                        </para></listitem>
                    </orderedlist>
                </para>

                <para>
                    <citation><xref linkend="freebsd-bylaws"/></citation>
                    <citation><xref linkend="freebsd-expiration-policy"/></citation>
                    <citation><xref linkend="freebsd-new-account"/></citation>
                </para>

            </section>

            <section id="process-cvsupmirror" xreflabel="Adding an official
                CVSup Mirror">
                <title>Adding/Removing an official CVSup Mirror</title>

                <para>
                    A <xref linkend="tool-cvsup"/> mirror is a replica of the
                    official CVSup master that contains all the up-to-date source
                    code for all the branches in the FreeBSD project, ports and
                    documentation.
                </para>

                <para>
                    Adding an official CVSup mirror starts with the potential
                    <xref linkend="role-cvsup-sitemaint"/> installing the
                    <quote>cvsup-mirror</quote> package. Having done this and
                    updated the source code with a mirror site, he now runs a
                    fairly recent unofficial CVSup mirror.
                </para>

                <para>
                    Deciding he has a stable environment, the processing
                    power, the network capacity and the
                    storage capacity to run an official mirror, he mails the
                    <xref linkend="role-cvsup-coordinator"/> who decides whether
                    the mirror should become an official mirror or not.
                </para>

                <para>
                    In making this decision, the <xref linkend="role-cvsup-coordinator"/>
                    has to determine whether that geographical area needs
                    another mirror site, if the mirror administrator has the
                    skills to run it reliably, if the network bandwidth is
                    adequate and if the master server has the capacity to server
                    another mirror.
                </para>

                <para>
                    If <xref linkend="role-cvsup-coordinator"/> decides that the
                    mirror should become an official mirror, he obtains an
                    authentication key from the mirror admin that he installs so
                    the mirror admin can update the mirror from the master server.
                </para>

                <para>
                    <figure>
                        <title>Process summary: adding a CVSup mirror</title>
                        <graphic fileref="proc-add-cvsup"/>
                    </figure>
                </para>

                <para>
                    When a CVSup mirror administrator of an unofficial mirror
                    offers to become an official mirror site, the CVSup
                    coordinator decides if another mirror is needed and if
                    there is sufficient capacity to accommodate it. If so,
                    an authorisation key is requested and the mirror is given
                    access to the main distribution site and added to the
                    list of official mirrors.
                </para>


                <para>
                    Tools used in this process:
                    <itemizedlist>
                        <listitem><para>
                                <xref linkend="tool-cvsup"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="tool-ssh2"/>
                        </para></listitem>
                    </itemizedlist>
                </para>

                <para>
                    Hats involved in this process:
                    <itemizedlist>
                        <listitem><para>
                                <xref linkend="role-cvsup-coordinator"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-cvsup-sitemaint"/>
                        </para></listitem>
                    </itemizedlist>
                </para>

            </section>

            <section id="committing">
                <title>Committing code</title>

                <para>
                    The committing of new or modified code is one of the most
                    frequent processes in the FreeBSD project and will usually
                    happen many times a day. Committing of code can only be done
                    by a <quote>committer</quote>. Committers commit either code
                    written by themselves, code submitted to them or code
                    submitted through a <link linkend="model-pr">problem
                    report</link>.
                </para>

                <para>
                    When code is written by the developer that is non-trivial, he
                    should seek a code review from the community. This
                    is done by sending mail to the relevant list asking for
                    review. Before submitting the code for review, he should
                    ensure it compiles correctly with the entire tree and that all
                    relevant tests run. This is called <quote>pre-commit
                    test</quote>. When contributed code is received, it should be
                    reviewed by the committer and tested the same way.
                </para>

                <para>
                    When a change is committed to a part of the source that
                    has been contributed from an outside
                    <xref linkend="role-vendor"/>,
                    the maintainer should
                    ensure that the patch is contributed back to the
                    vendor. This is in line with the open source
                    philosophy and
                    makes it easier to stay in sync with outside projects
                    as the patches do not have to be reapplied every time a
                    new release is made.
                </para>

                <para>
                    After the code has been available for review and no further
                    changes are necessary, the code is committed into the
                    development branch, -CURRENT.
                    If the change applies for
                    the -STABLE branch or the other branches as well, a
                    <quote>Merge From Current</quote> ("MFC") countdown is
                    set by the committer. After the number of days the
                    committer chose when setting the MFC have passed, an email
                    will automatically be
                    sent to the committer reminding him to commit it to the -STABLE
                    branch (and possibly security branches as well). Only security
                    critical changes should be merged to security branches.
                </para>

                <para>
                    Delaying the commit to -STABLE and other branches allows for
                    <quote>parallel debugging</quote> where the committed code is
                    tested on a wide range of configurations. This makes changes
                    to -STABLE to contain fewer faults and thus giving the branch
                    its name.
                </para>

                <para>
                    <figure>
                        <title>Process summary: A committer commits code</title>
                        <graphic fileref="proc-commit"/>
                    </figure>
                </para>

                <para>
                    When a committer has written a piece of code and
                    wants to commit it, he first needs to determine if it is
                    trivial enough to go in without prior review or if it should
                    first be reviewed by the developer community. If the code is
                    trivial or has been reviewed and the committer is not the
                    maintainer, he should consult the maintainer before
                    proceeding.
                    If the code is contributed by an outside vendor, the
                    maintainer should create a patch that is sent back to the
                    vendor. The code is then committed and the deployed by
                    the users. Should they find problems with the code, this
                    will be reported and the committer can go back to writing
                    a patch. If a vendor is affected, he can choose to
                    implement or ignore the patch.
                </para>

                <para>
                    <figure>
                        <title>Process summary: A contributor commits code</title>
                        <graphic fileref="proc-contrib"/>
                    </figure>
                </para>

                <para>
                    The difference when a contributor makes a code contribution is
                    that he submits the code through the send-pr
                    program. This report is picked up by the maintainer who
                    reviews the code and commits it.
                </para>

                <para>
                    Hats included in this process are:
                    <orderedlist>
                        <listitem><para>
                                <xref linkend="role-committer"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-contributor"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-vendor"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-reviewer"/>
                        </para></listitem>
                    </orderedlist>
                </para>

                <para>
                    <citation><xref linkend="freebsd-committer"/></citation>
                    <citation><xref linkend="jorgensen2001"/></citation>
                </para>

            </section>

            <section id="process-core-election" xreflabel="Core election">
                <title>Core election</title>

                <para>
                    Core elections are held at least every two years.
                    <footnote>
                        <para>The first Core election was held September 2000</para>
                    </footnote>
                    Nine core members are elected.  New elections are held if
                    the number of core members drops below seven. New elections can
                    also be held should at least 1/3 of the active committers demand this.
                </para>

                <para>
                    When an election is to take place, core announces this at
                    least 6 weeks in advance, and appoints an election manager to
                    run the elections.

                </para>

                <para>
                    Only committers can be elected into core. The candidates need
                    to submit their candidacy at least one week before the
                    election starts, but can refine their statements until the
                    voting starts. They are
                    presented in the <ulink
                        url="http://election.uk.freebsd.org/candidates.html">candidates
                    list</ulink>. When writing their election statements, the candidates
                    must answer a few standard questions submitted by the election manager.
                </para>

                <para>
                    During elections, the rule that a committer must have
                    committed during the 12 past months is followed strictly.
                    Only these committers are eligible to vote.

                </para>

                <para>
                    When voting, the committer may vote once in support of up to
                    nine nominees. The voting is done over a period of four weeks
                    with reminders being posted on <quote>developers</quote>
                    mailing list that is available to all committers.
                </para>

                <para>
                    The election results are released one week after the election
                    ends, and the new core team takes office one week after the
                    results have been posted.
                </para>

                <para>
                    Should there be a voting tie, this will be resolved by
                    the new, unambiguously elected core members.
                </para>

                <para>
                    Votes and candidate statements are archived, but the archives
                    are not publicly available.
                </para>

                <para>
                    <figure>
                        <title>Process summary: Core elections</title>
                        <graphic fileref="proc-elections"/>
                    </figure>
                </para>

                <para>
                    Core announces the election and selects an election
                    manager. He prepares the elections, and when ready,
                    candidates can announce their candidacies through
                    submitting their statements. The committers then vote.
                    After the vote is over, the election results are
                    announced and the new core team takes office.
                </para>

                <para>
                    Hats in core elections are:
                    <itemizedlist>
                        <listitem><para>
                                <xref linkend="role-core"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-committer"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-election-manager"/>
                        </para></listitem>

                    </itemizedlist>

                </para>


                <para>
                    <citation><xref linkend="freebsd-bylaws"/></citation>
                    <citation><xref linkend="bsd-election2002"/></citation>
                    <citation><xref linkend="freebsd-election"/></citation>
                </para>
            </section>

            <section id="new-features">
                <title>Development of new features</title>

                <para>
                    Within the project there are sub-projects that are working on
                    new features. These projects are generally done by one person
                    <citation><xref linkend="jorgensen2001"/></citation>.
                    Every project is free to
                    organise development as it sees fit. However, when the project
                    is merged to the -CURRENT branch it must follow the project
                    guidelines. When the code has been well tested in the
                    -CURRENT branch and deemed stable enough and relevant
                    to the -STABLE branch, it is merged to the -STABLE branch.
                </para>

                <para>
                    The requirements of the project are given by developer
                    wishes, requests from the community in terms of direct
                    requests by mail, Problem Reports, commercial funding for the development
                    of features, or contributions by the scientific community.
                    The wishes that come within the responsibility of a developer
                    are given to that developer who prioritises his time between
                    the request and his wishes. A common way to do this is maintain
                    a TODO-list maintained by the project. Items that do not come within
                    someone's responsibility are collected on TODO-lists unless someone
                    volunteers to take the responsibility. All
                    requests, their distribution and follow-up are
                    handled by the <xref linkend="tool-gnats"/> tool.
                </para>

                <para>
                    Requirements analysis happens in two ways. The requests that
                    come in are discussed on mailing lists, both within the main
                    project and in the sub-project that the request belongs to or is
                    spawned by the request. Furthermore, individual developers on
                    the sub-project will evaluate the feasibility of the requests
                    and determine the prioritisation between them. Other than archives
                    of the discussions that have taken place, no outcome is created
                    by this phase that is merged into the main project.
                </para>

                <para>
                    As the requests are prioritised by the individual developers on
                    the basis of doing what they find interesting, necessary or are
                    funded to do, there is no overall strategy or priorisation of
                    what requests to regard as requirements and following up their
                    correct implementation. However, most developers have some
                    shared vision of what issues are more important, and they can
                    ask for guidelines from the release engineering team.
                    <!-- and
                    technical review board.
   					[TODO] TRB is undefined at the moment -->
                </para>

                <para>
                    The verification phase of the project is two-fold. Before
                    committing code to the current-branch, developers request their
                    code to be reviewed by their peers. This review is for the most
                    part done by functional testing, but also code review is
                    important. When the code is committed to the branch, a broader
                    functional testing will happen, that may trigger further code
                    review and debugging should the code not behave as
                    expected. This second verification form may be regarded as
                    structural verification.
                    Although the sub-projects themselves may write formal
                    tests such as unit tests, these are usually not collected by the main
                    project and are usually removed before the code is committed to
                    the current branch.
                    <footnote>
                        <para>
                            More and more tests are however performed when
                            building the system (<quote>make
                            world</quote>). These tests are however a very new
                            addition and no systematic framework for these
                            tests have yet been created.
                        </para>

                    </footnote>
                </para>

            </section>


            <section id="model-maintenance" xreflabel="maintenance">
                <title>Maintenance</title>

                <para>

                    It is an advantage to the project to for each area of the source
                    have at least one person that knows this area well.

                    Some parts of the code have designated
                    maintainers. Others have de-facto maintainers, and some
                    parts of the system do not have
                    maintainers.

                    The maintainer is usually a person from the sub-project that
                    wrote and integrated the code, or someone who has ported it from
                    the platform it was written for.
                    <footnote>
                        <para>
                            sendmail and named are examples of code that has been merged
                            from other platforms.
                        </para>
                    </footnote>

                    The maintainer's job is to make sure the code is in sync with the
                    project the code comes from if it is contributed code, and apply patches
                    submitted by the community or write fixes to issues that are
                    discovered.

                </para>

                <para>
                    The main bulk of work that is put into the FreeBSD project is
                    maintenance. <citation><xref
                    linkend="jorgensen2001"/></citation>
                    has made a figure
                    showing the life cycle of changes.
                </para>

                <para>
                    <figure>
                        <title>J&oslash;rgenssen's model for change integration</title>
                        <graphic fileref="maintenance"/>
                    </figure>
                </para>

                <para>

                    Here <quote>development release</quote> refers to the -CURRENT
                    branch while <quote>production release</quote> refers to the
                    -STABLE branch. The <quote>pre-commit test</quote> is the
                    functional testing by peer developers when asked to do so or
                    trying out the code to determine the status of the sub-project.
                    <quote>Parallel debugging</quote> is the functional testing
                    that can trigger more review, and debugging when the code is
                    included in the -CURRENT branch.
                </para>


                <para>
                    As of this writing, there were 269 committers in the
                    project. When they commit a change to a branch, that constitutes
                    a new release. It is very common for users in the community to
                    track a particular branch. The immediate existence of a new
                    release makes the changes widely available right away and allows
                    for rapid feedback from the community. This also gives the
                    community the response time they expect on issues that are of
                    importance to them. This makes the community more engaged, and
                    thus allows for more and better feedback that again spurs more
                    maintenance and ultimately should create a better product.
                </para>

                <para>
                    Before making changes to code in parts of the tree
                    that has a history unknown to the committer, the
                    committer is required to read the commit logs to see why
                    certain features are implemented the way they are in
                    order not to make mistakes that have previously either been
                    thought through or resolved.

                </para>

            </section>

            <section id="model-pr">
                <title>Problem reporting</title>

                <para>
                    FreeBSD comes with a problem reporting tool called
                    <quote>send-pr</quote> that is a part of the GNATS package.
                    All users and developers are encouraged to use this tool for
                    reporting problems in software they do not maintain. Problems
                    include bug reports, feature requests, features that should be enhanced
                    and notices of new versions of external software that is included
                    in the project.
                </para>

                <para>
                    Problem reports are sent to an email address where it
                    is inserted into the GNATS maintenance database. A
                    <xref linkend="role-bugbuster"/>
                    classifies the problem and sends it to the
                    correct group or maintainer within the project. After someone
                    has taken responsibility for the report, the report is being
                    analysed. This analysis includes verifying the problem and
                    thinking out a solution for the problem. Often feedback is
                    required from the report originator or even from the FreeBSD
                    community. Once a patch for the problem is made, the
                    originator may be asked to try it out. Finally, the working patch
                    is integrated into the project, and documented if
                    applicable. It there goes through the regular maintenance
                    cycle as described in section <xref linkend="model-maintenance"/>.
                    These are the states a problem report can be in:
                    open, analyzed, feedback, patched, suspended and closed. The
                    suspended state is for when further progress is not possible
                    due to the lack of information or for when the task would require
                    so much work that nobody is working on it at the moment.
                </para>

                <para>
                    <figure>
                        <title>Process summary: problem reporting</title>
                        <graphic fileref="proc-pr"/>
                    </figure>
                </para>

                <para>
                    A problem is reported by the report originator. It is
                    then classified by a bugbuster and handed to the correct
                    maintainer. He verifies the problem and discusses the
                    problem with the originator until he has enough
                    information to create a working patch. This patch is then
                    committed and the problem report is closed.
                </para>


                <para>
                    The roles included in this process are:
                    <orderedlist>
                        <listitem><para>
                                <xref linkend="role-problem-originator"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-maintainer"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-bugbuster"/>
                        </para></listitem>
                    </orderedlist>
                </para>

                <para>
                    <citation><xref linkend="freebsd-handle-pr"/></citation>.
                    <citation><xref linkend="freebsd-send-pr"/></citation>
                </para>

            </section>

            <section id="process-reactions" xreflabel="Reacting to misbehaviour">
                <title>Reacting to misbehaviour</title>

                <para>
                    <citation><xref linkend="freebsd-committer"/></citation> has a
                    number of rules that committers should follow. However, it
                    happens that these rules are broken. The following rules exist
                    in order to be able to react to misbehaviour. They specify what
                    actions will result in how long a suspension the committer's
                    commit privileges.

                    <itemizedlist>
                        <listitem><para>
                                Committing during code freezes without the approval of the
                                Release Engineering team - 2 days
                        </para></listitem>
                        <listitem><para>
                                Committing to a security branch without approval - 2 days
                        </para></listitem>
                        <listitem><para>
                                Commit wars - 5 days to all participating parties
                        </para></listitem>
                        <listitem><para>
                                Impolite or inappropriate behaviour - 5 days
                        </para></listitem>
                    </itemizedlist>

                    <citation><xref linkend="ref-freebsd-trenches"/></citation>
                </para>

                <para>
                    For the suspensions to be efficient, any single core member can
                    implement a suspension before discussing it on the <quote>core</quote>
                    mailing list. Repeat offenders can, with a 2/3 vote by core,
                    receive harsher penalties, including permanent removal of
                    commit privileges. (However, the latter is always viewed as a last
                    resort, due to its inherent tendency to create controversy).  All
                    suspensions are posted to the
                    <quote>developers</quote>
                    mailing list, a list available to committers only.
                </para>

                <para>
                    It is important that you cannot be suspended for making
                    technical errors. All penalties come from breaking social etiquette.
                </para>

                <para>
                    Hats involved in this process:
                    <itemizedlist>
                        <listitem><para>
                                <xref linkend="role-core"/>
                        </para></listitem>
                        <listitem><para>
                                <xref linkend="role-committer"/>
                        </para></listitem>
                    </itemizedlist>
                </para>
            </section>


            <section id="process-release-engineering" xreflabel="release engineering">
                <title>Release engineering</title>

                <para>
                    The FreeBSD project has a Release Engineering <!-- ("RE") --> team with a
                    principal release engineer that is responsible for creating releases
                    of FreeBSD that can be brought out to the user community via the
                    net or sold in retail outlets. Since FreeBSD is available on multiple
                    platforms and releases for the different architectures are made
                    available at the same time, the team has one person in charge of
                    each architecture. Also, there are roles in the team responsible
                    for coordinating quality assurance <!-- ("QA") --> efforts, building a package
                    set and for having an updated set of documents.
                    When referring to the release engineer,
                    a representative for the release engineering team is
                    meant.
                </para>

                <para>
                    When a release is coming, the FreeBSD project changes shape
                    somewhat. A release schedule is made containing feature- and
                    code-freezes, release of interim releases and the final
                    release. A feature-freeze means no new features are allowed to
                    be committed to the branch without the release engineers'
                    explicit consent. Code-freeze means no changes to the code (like
                    bugs-fixes) are allowed to be committed without the release
                    engineers explicit consent. This feature- and code-freeze is
                    known as stabilising. During the release process, the release
                    engineer has the full authority to revert to older versions of
                    code and thus "back out" changes should he find that the changes
                    are not suitable to be included in the release.
                </para>

                <para>
                    There are three different kinds of releases:
                    <orderedlist>
                        <listitem><para>
                                .0 releases are the first release of a major
                                version. These are branched of the -CURRENT branch
                                and have a significantly longer release engineering
                                cycle due to the unstable nature of the -CURRENT branch
                        </para></listitem>
                        <listitem><para>
                                .X releases are releases of the -STABLE
                                branch. They are scheduled to come out every 4 months.
                        </para></listitem>
                        <listitem><para>
                                .X.Y releases are security releases that follow
                                the .X branch. These come out only when sufficient
                                security fixes have been merged since the last
                                release on that branch. New features are rarely
                                included, and the security team is far more
                                involved in these than in regular releases.

                        </para></listitem>
                    </orderedlist>

                </para>

                <para>
                    For releases of the -STABLE-branch, the release process starts 45
                    days before the anticipated
                    release date. During the first phase, the first 15 days, the
                    developers merge what changes they have had in -CURRENT
                    that they want to have in the release to the release
                    branch. When this period is over, the code enters a 15
                    day code freeze in which only bug fixes, documentation updates,
                    security-related fixes and minor device driver changes are
                    allowed. These changes must be approved by the release engineer
                    in advance. At the beginning of the last 15 day period a release
                    candidate is created for widespread testing. Updates are less
                    likely to be allowed during this period, except for important
                    bug fixes and security updates. In this final period, all
                    releases are considered release candidates. At the end of the
                    release process, a release is created with the new version
                    number, including binary distributions on web sites and the
                    creation of a CD-ROM images.  However, the release is not
                    considered "really released" until a <xref linkend="tool-pgp"/>-signed message stating
                    exactly that, is sent to the mailing list freebsd-announce; anything
                    labelled as a "release" before that may well be in-process and
                    subject to change before the PGP-signed message is sent.

                    <footnote>
                        <para>
                            Many commercial vendors use these images to create
                            CD-ROMs that are sold in retail outlets.
                        </para>
                    </footnote>.


                </para>

                <para>
                    The releases of the -CURRENT-branch (that is, all releases that
                    end with <quote>.0</quote>) are very similar, but with twice as
                    long timeframe. It starts 8 weeks prior to the release with
                    announcement of the release time line. Two weeks into the
                    release process, the feature freeze is initiated and performance
                    tweaks should be kept to a minimum. Four weeks prior to the
                    release, an official beta version is made available. Two weeks
                    prior to release, the code is officially branched into a new
                    version. This version is given release candidate status, and as
                    with the release engineering of -STABLE, the code freeze of the
                    release candidate is
                    hardened. However, development on the main development branch
                    can continue. Other than these differences, the release
                    engineering processes are alike.

                </para>

                <para>
                    .0 releases go into their own branch and are aimed
                    mainly at early adopters. The branch then goes through a period
                    of stabilisation, and it is not until the <xref linkend="role-releng"/>
                    decides the demands to stability have been satisfied that
                    the branch becomes -STABLE and -CURRENT targets the next major
                    version. While this for the majority has been with .1 versions,
                    this is not a demand.
                </para>

                <para>
                    Most releases are made when a given date that has been deemed a
                    long enough time since the previous release comes. A target is
                    set for having major releases every 18 months and minor
                    releases every 4 months.

                    The user community has made it very clear that security and
                    stability cannot be sacrificed by self-imposed deadlines and
                    target release dates.

                    For slips of time not to become too long with regards to security
                    and stability issues,
                    extra discipline is required when committing changes to -STABLE.

                </para>


                <para>
                    <figure>
                        <title>Process summary: release engineering</title>
                        <graphic fileref="proc-releng"/>
                    </figure>
                </para>

                <para>
                    These are the stages in the release engineering
                    process. Multiple release candidates may be created until
                    the release is deemed stable enough to be released.
                </para>


                <para>
                    <citation><xref linkend="freebsd-releng"/></citation>
                </para>

            </section>


        </chapter>




        <chapter id="tools">
            <title>Tools</title>

            <para>
                The major support tools for supporting the development process are
                CVS, CVSup, Perforce, GNATS, Mailman and OpenSSH. Except for
                CVSup, these are externally
                developed tools. These tools are commonly used in the open source world.
            </para>

            <section id="tool-svn" xreflabel="SVN">
                <title>Subversion (SVN)</title>
                <para>Subversion (<quote>SVN</quote>)
                    is a system to handle multiple versions of text files and
                    tracking who committed what changes and why. A project lives
                    within a <quote>repository</quote> and different versions are
                    considered different <quote>branches</quote>.
                </para>
            </section>

            <section id="tool-cvsup" xreflabel="CVSup">
                <title>CVSup</title>
                <para>
                    CVSup is a software package for distributing and updating
                    collections of files across a network. It consists of a
                    client program, cvsup, and a server program, cvsupd. The
                    package is tailored specifically for distributing CVS
                    repositories, and by taking advantage of CVS' properties, it
                    performs updates much faster than traditional systems.
                </para>
            </section>

            <section id="tool-gnats" xreflabel="GNATS">
                <title>GNATS</title>
                <para>
                    GNATS is a maintenance database consisting of a set of tools to track bugs at a
                    central site. It supports the bug tracking process for sending
                    and handling bugs as well as querying and updating the database
                    and editing bug reports. The project uses one of its many client
                    interfaces, <quote>send-pr</quote>, to send
                    <quote>Problem Reports</quote> by email to the
                    projects central GNATS server. The committers have also web and
                    command-line clients available.
                </para>
            </section>

            <section id="model-mailman" xreflabel="[model, Mailman]">
                <title>Mailman</title>
                <para>
                    Mailman is a program that automates the
                    management of mailing lists. The FreeBSD Project uses it to run
                    16 general lists, 60 technical lists, 4 limited lists and 5 lists
		    with CVS commit logs. It is
                    also used for many mailing lists set up and used by other people
                    and projects in the FreeBSD community. General lists are lists
                    for the general public, technical lists are mainly for the
                    development of specific areas of interest, and closed lists
                    are for internal communication not intended for the general
                    public. The majority of all the communication in the project goes
                    through these 85 lists
                    <citation><xref linkend="ref-bsd-handbook"/>, Appendix C</citation>.

                </para>
            </section>

            <section id="tool-perforce" xreflabel="Perforce">
                <title>Perforce</title>
                <para>
                    Perforce is a commercial software configuration management
                    system developed by Perforce
                    Systems that is available on over 50 operating systems. It
                    is a collection of clients built around the Perforce server
                    that contains the central file repository and
                    tracks the operations done upon it. The clients are both
                    clients for accessing the repository and administration of
                    its configuration.

                    <!-- REF: http://www.perforce.com/perforce/products.html  -->

                </para>
            </section>


            <section id="tool-pgp" xreflabel="PGP">
                <title>Pretty Good Privacy</title>
                <para>
                    Pretty Good Privacy, better known as PGP, is a cryptosystem
                    using a public key architecture to allow people to digitally
                    sign and/or encrypt information in order to ensure secure
                    communication between two parties. A signature is used when
                    sending information out many recipients, enabling them to verify
                    that the information has not been tampered with before they
                    received it. In the FreeBSD Project this is the primary means of
                    ensuring that information has been written by the person who
                    claims to have written it, and not altered in transit.
                </para>
            </section>

            <section id="tool-ssh2" xreflabel="SSH 2">
                <title>Secure Shell</title>
                <para>
                    Secure Shell is a standard for securely logging into a remote system
                    and for executing commands on the remote system. It allows
                    other connections, called tunnels, to be established and
                    protected between the two involved systems. This standard
                    exists in two primary versions, and only version two is used
                    for the FreeBSD Project. The most common implementation of the
                    standard is OpenSSH that is a part of the project's main distribution.
                    Since its source is updated more often than FreeBSD releases,
                    the latest version is also available in the ports tree.
                </para>
            </section>

        </chapter>

        <chapter id="sub-projects">
            <title>Sub-projects</title>

            <para>
                Sub-projects are formed to reduce the amount of communication
                needed to coordinate the group of developers. When a problem
                area is sufficiently isolated, most communication would be
                within the group focusing on the problem, requiring less
                communication with the groups they communicate with than were
                the group not isolated.

            </para>

            <section id="sub-project-ports" xreflabel="The Ports Subproject">
                <title>The Ports Subproject</title>

                <para>
                    A <quote>port</quote> is a set of meta-data and patches that
                    are needed to fetch, compile and install correctly an external piece of
                    software on a FreeBSD system. The amount of ports have grown
                    at a tremendous rate, as shown by the following figure.
                </para>

                <para>
                    <figure id="fig-ports">
                        <title>Number of ports added between 1996 and 2005</title>
                        <graphic fileref="portsstatus"/>
                    </figure>
                </para>

                <para>
                    <xref linkend="fig-ports"/> is taken from
                    <ulink url="http://www.freebsd.org/ports/growth/status.png">
                    the FreeBSD web site</ulink>. It shows the number of ports
                    available to FreeBSD in the period 1995 to 2005. It looks
                    like the curve has first grown exponentionally, and then
                    since the middle of 2001 grown linearly.
                </para>

                <para>
                    As the external software described by the port often is under
                    continued development, the amount of work required to maintain
                    the ports is already large, and increasing. This has led to
                    the ports part of the FreeBSD project gaining a more empowered
                    structure, and is more and more becoming a sub-project of the
                    FreeBSD project.
                </para>

                <para>
                    Ports has its own core team with the
                    <xref linkend="role-ports-manager"/> as its leader, and this
                    team can appoint committers without FreeBSD Core's
                    approval. Unlike in the FreeBSD Project, where a lot of maintenance
                    frequently is rewarded with a commit bit, the ports sub-project
                    contains many active maintainers that are not committers.
                </para>

                <para>
                    Unlike the main project, the ports tree is not branched. Every
                    release of FreeBSD follows the current ports collection and has thus
                    available updated information on where to find programs and
                    how to build them. This, however, means that a port that makes
                    dependencies on the system may need to have variations
                    depending on what version of FreeBSD it runs on.
                </para>

                <para>
                    With an unbranched ports repository
                    it is not possible to guarantee that any port
                    will run on anything other than -CURRENT and -STABLE, in
                    particular older, minor releases. There is neither the infrastructure
                    nor volunteer time needed to guarantee this.
                </para>

                <para>
                    For efficiency of communication, teams depending on Ports,
                    such as the release engineering team, have their own ports liaisons.
                </para>


            </section>


            <section id="sub-project-documentation" xreflabel="The FreeBSD
                Documentation Project">
                <title>The FreeBSD Documentation Project</title>

                <para>
		<!-- [TODO] - Recount, according to the statistics there were only
		              9 mainly Doc-committers in 2004. Get mailinglist data  -->
                    The FreeBSD Documentation project was started January 1995. From
                    the initial group of a project leader, four team leaders and 16
                    members, they are now a total of 44 committers. The
                    documentation mailing list has just under 300 members,
                    indicating that there is quite a large community around it.
                </para>

                <para>
                    The goal of the Documentation project is to provide good and
                    useful documentation of the FreeBSD project, thus making it
                    easier for new users to get familiar with the system and
                    detailing advanced features for the users.
                </para>

                <para>
                    The main tasks in the Documentation project are to work on
                    current projects in the <quote>FreeBSD Documentation Set</quote>,
                    and translate the documentation to other languages.
                </para>

                <para>
                    Like the FreeBSD Project, documentation is split in the same
                    branches. This is done so that there is always an updated
                    version of the documentation for each version. Only
                    documentation errors are corrected in the security branches.
                </para>

                <para>
                    Like the ports sub-project, the Documentation project can
                    appoint documentation committers without FreeBSD Core's approval.
                    <citation><xref linkend="freebsd-doceng-charter"/></citation>.
                </para>

                <para>
                    The Documentation project has a primer. This is used both to
                    introduce new project members to the standard tools and
                    syntaxes and acts as a reference when working on the project.
                </para>

            </section>


    </chapter>

<bibliography id="bibliography">
        <title>References</title>

  <biblioentry id="brooks" xreflabel="Brooks, 1995">
    <authorgroup>
      <author><firstname>Frederick P.</firstname><surname>Brooks</surname></author>
    </authorgroup>
    <copyright><year>1975</year><year>1995</year>
      <holder>Pearson Education Limited</holder>
    </copyright>
    <isbn>0201835959</isbn>
    <publisher>
      <publishername>Addison-Wesley Pub Co</publishername>
    </publisher>
    <title>The Mythical Man-Month</title>
    <subtitle>Essays on Software Engineering, Anniversary Edition (2nd Edition)</subtitle>
  </biblioentry>

        <biblioentry id="thesis" xreflabel="Saers, 2003">
            <authorgroup>
                <author><firstname>Niklas</firstname><surname>Saers</surname></author>
            </authorgroup>
            <copyright>
                <year>2003</year>
            </copyright>
            <title>A project model for the FreeBSD Project</title>
            <subtitle>Candidatus Scientiarum thesis</subtitle>
            <bibliomisc role="url"><ulink url="http://niklas.saers.com/thesis"></ulink></bibliomisc>
        </biblioentry>


        <biblioentry id="jorgensen2001" xreflabel="J&oslash;rgensen, 2001">
            <authorgroup>
                <author><firstname>Niels</firstname><surname>J&oslash;rgensen</surname></author>
            </authorgroup>
            <copyright>
                <year>2001</year>
            </copyright>
            <title>Putting it All in the Trunk</title>
            <subtitle>Incremental Software Development in the FreeBSD Open Source Project</subtitle>
            <bibliomisc role="url"><ulink url="http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="ref-pmbok" xreflabel="PMI, 2000">
            <authorgroup>
                <author><surname>Project Management Institute</surname></author>
            </authorgroup>
            <copyright><year>1996</year><year>2000</year>
                <holder>Project Management Institute</holder>
            </copyright>
            <isbn>1-880410-23-0</isbn>
            <publisher>
                <publishername>Project Management Institute</publishername>
                <address>
                    <street>Newtown Square</street>
                    <city>Pennsylvania</city>
                    <country>USA</country>
                </address>
            </publisher>
            <title>PMBOK Guide</title>
            <subtitle>A Guide to the Project Management Body of Knowledge,
            2000 Edition</subtitle>
        </biblioentry>



        <biblioentry id="freebsd-bylaws" xreflabel="FreeBSD, 2000A">
            <copyright><year>2002</year>
                <holder>The FreeBSD Project</holder>
            </copyright>
            <title>Core Bylaws</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/bylaws.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-developer-handbook" xreflabel="FreeBSD, 2002A">
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <title>FreeBSD Developer's Handbook</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="bsd-election2002" xreflabel="FreeBSD, 2002B">
            <copyright><year>2002</year>
                <holder>The FreeBSD Project</holder>
            </copyright>
            <title>Core team election 2002</title>
            <bibliomisc role="url"><ulink url="http://election.uk.freebsd.org/candidates.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-handle-pr" xreflabel="FreeBSD, 2002C">
            <authorgroup>
                <author><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></author>
                <author><firstname>Hiten</firstname><surname>Pandya</surname></author>
            </authorgroup>
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <title>Problem Report Handling Guidelines</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-send-pr" xreflabel="FreeBSD, 2002D">
            <authorgroup>
                <author><firstname>Dag-Erling</firstname><surname>Sm&oslash;rgrav</surname></author>
            </authorgroup>
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <title>Writing FreeBSD Problem Reports</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/problem-reports/article.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-committer" xreflabel="FreeBSD, 2001">
            <copyright><year>2001</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <!-- Version 1.146 -->
            <title>Committers Guide</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/committers-guide/article.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-releng" xreflabel="FreeBSD, 2002E">
            <authorgroup>
                <author><firstname>Murray</firstname><surname>Stokely</surname></author>
            </authorgroup>
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <!-- Version 1.42 -->
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <title>FreeBSD Release Engineering</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="ref-bsd-handbook" xreflabel="FreeBSD, 2003A">
            <authorgroup>
                <author><surname>The FreeBSD Documentation Project</surname></author>
            </authorgroup>
            <title>FreeBSD Handbook</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-contributors" xreflabel="FreeBSD, 2002F">
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <title>Contributors to FreeBSD</title>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/article.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-election" xreflabel="FreeBSD, 2002G">
            <copyright><year>2002</year>
                <holder>The FreeBSD Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Project</publishername>
            </publisher>
            <title>Core team elections 2002</title>
            <bibliomisc role="url"><ulink url="http://election.uk.freebsd.org"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-expiration-policy" xreflabel="FreeBSD, 2002H">
            <copyright><year>2002</year>
                <holder>The FreeBSD Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Project</publishername>
            </publisher>
            <title>Commit Bit Expiration Policy</title>
            <subtitle>2002/04/06 15:35:30</subtitle>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/expire-bits.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-new-account" xreflabel="FreeBSD, 2002I">
            <copyright><year>2002</year>
                <holder>The FreeBSD Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Project</publishername>
            </publisher>
            <title>New Account Creation Procedure</title>
            <subtitle>2002/08/19 17:11:27</subtitle>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/new-account.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="freebsd-doceng-charter" xreflabel="FreeBSD, 2003B">
            <copyright><year>2002</year>
                <holder>The FreeBSD Documentation Project</holder>
            </copyright>
            <publisher>
                <publishername>The FreeBSD Documentation Project</publishername>
            </publisher>
            <title>FreeBSD DocEng Team Charter</title>
            <subtitle>2003/03/16 12:17</subtitle>
            <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/doceng.html"></ulink></bibliomisc>
        </biblioentry>

        <biblioentry id="ref-freebsd-trenches" xreflabel="Lehey, 2002">
            <authorgroup>
                <author><firstname>Greg</firstname><surname>Lehey</surname></author>
            </authorgroup>
            <copyright><year>2002</year>
                <holder>Greg Lehey</holder>
            </copyright>
            <publisher>
                <publishername>Greg Lehey</publishername>
            </publisher>
            <title>Two years in the trenches</title>
            <subtitle>The evolution of a software project</subtitle>
            <bibliomisc role="url"><ulink url="http://www.lemis.com/grog/In-the-trenches.pdf"></ulink></bibliomisc>
        </biblioentry>
    </bibliography>

</book>