diff --git a/en_US.ISO8859-1/books/dev-model/Makefile b/en_US.ISO8859-1/books/dev-model/Makefile new file mode 100644 index 0000000000..bfdb7a3992 --- /dev/null +++ b/en_US.ISO8859-1/books/dev-model/Makefile @@ -0,0 +1,34 @@ +# +# $FreeBSD$ +# + +MAINTAINER= des@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= book.sgml + +IMAGES_EN= figures/branches.png +IMAGES_EN+= figures/freebsd-code-model.png +IMAGES_EN+= figures/hats-overview.png +IMAGES_EN+= figures/maintenance.png +IMAGES_EN+= figures/orghierarchy.png +IMAGES_EN+= figures/orghierarchy2.png +IMAGES_EN+= figures/portsstatus.png +IMAGES_EN+= figures/proc-add-committer.png +IMAGES_EN+= figures/proc-add-cvsup.png +IMAGES_EN+= figures/proc-commit.png +IMAGES_EN+= figures/proc-contrib.png +IMAGES_EN+= figures/proc-elections.png +IMAGES_EN+= figures/proc-pr.png +IMAGES_EN+= figures/proc-releng.png +IMAGES_EN+= figures/proc-rm-committer.png + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/books/dev-model/book.sgml b/en_US.ISO8859-1/books/dev-model/book.sgml new file mode 100644 index 0000000000..2488f2ce89 --- /dev/null +++ b/en_US.ISO8859-1/books/dev-model/book.sgml @@ -0,0 +1,2690 @@ +<!-- + - Copyright (c) 2002-2003 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$ + --> + +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"> +%bookinfo; +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; +<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN"> +%freebsd; +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +<!ENTITY % chap.index "IGNORE"> +]> + +<book> + <bookinfo> + <title>A project model for the FreeBSD Project</title> + <author> + <firstname>Niklas</firstname> + <surname>Saers</surname> + </author> + <copyright> + <year>2002, 2003</year> + <holder>Niklas Saers</holder> + </copyright> + <revhistory> + <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> + </bookinfo> + <preface> + + <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ø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ø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 year + 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 + April 1st, 2003. It is based on the Niels Jø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> + <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="figures/orghierarchy.png" format="PNG"> + </figure> + </para> + + <para> + Number of committers has been determined by going through + CVS logs from December 1st, 2001 to December 1st, 2002 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. + </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> + The project can be grouped into four distinct separate parts, + and most developers <!-- 57% by December 1st, 2002 --> + will during their involvement in the FreeBSD + project only be involved with one of these parts. 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="figures/orghierarchy2.png" format="PNG"> + </figure> + </para> + <para> + Number of committers per area has been determined by going through + CVS logs from December 1st, 2001 to December 1st, + 2002. 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 275. + </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, 99 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 are currently 41 + people involved in 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 + 7800 ports available. + <footnote> + <para> + Statistics are generated by counting the number of + entries in the file ports/INDEX by January 1st, 2003. + </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> + <title>Methodology model</title> + + <section><title>Development model</title> + + <para> + There is no defined model for how people write code in + FreeBSD. However, Niels Jørgenssen has suggested a model of + how written code is integrated into the project. + </para> + + <para> + <figure> + <title>Jørgenssen's model for change integration</title> + <graphic fileref="figures/maintenance.png" format="PNG"> + </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ø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 December 1st, 2001 to December 3rd, 2002 was + examined to find this number. + </para> + </footnote> + , 132148 commits were made, making a daily average of 360 + commits. + </para> + + <para> + Within the <quote>code</quote> bracket in Jø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ø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> + <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 + release called RELENG_4_5. + </para> + + <para> + <figure> + <title>The FreeBSD release tree</title> + <graphic fileref="figures/branches.png" format="PNG"> + </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.1-RELEASE or 5.2-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> + <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="figures/freebsd-code-model.png" format="PNG"> + </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 + <citation><xref linkend="bsd-hats"></citation>. + 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> + <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 make commits in + parts of the 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 January 1st, 2003, 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 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="figures/hats-overview.png" format="PNG"> + </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: + John Polstra <email>jdp@FreeBSD.org</email>. + </para> + </section> + + <section id="role-internationalisation" xreflabel="Internationalisation"> + <title>Internationalisation</title> + <para> + The Internationalisation hat is responsible for coordinating + the localisation efforts of the FreeBSD kernel and userland + utilities. The translation effort are coordinated by + <xref linkend="sub-project-documentation">. The + Internationalisation hat should suggest and promote standards + and guidelines for writing and maintaining the software in a + fashion that makes it easier to translate. + </para> + <para> + Hat currently available. + <!-- + Although Ache does Localization + Andrey A. Chernov <email>ache@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: + Jonathan M. Bresler <email>jmb@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> + Hat held by: + the Release Engineering team <email>re@FreeBSD.org</email>, + currently headed by + Murray Stokely <email>murray@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 & Corporate Liaison"> + <title>Public Relations & Corporate Liaison</title> + <para> + The Public Relations & 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> + <para> + Hat held by: + the Security Officer <email>security-officer@FreeBSD.org</email>, + currently headed by + Jacques Vidrine <email>nectar@FreeBSD.org</email>. + The + <ulink url="http://www.freebsd.org/security/index.html#sec"> + Security Officer and The Security Officer Team's + charter</ulink>. + </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-cvs"> 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>, + currently headed by Peter Wemm <email>peter@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 unforseen + events happen in the election process. Major unforseen + 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>, + currently headed by + Satoshi Asami <email>asami@FreeBSD.org</email>. + </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: + Wilko Bulte <email>wilko@FreeBSD.org</email>. + </para> + </section> + + <section id="role-xfree86" xreflabel="XFree86 Project, Inc. Liaison"> + <title>XFree86 Project, Inc. Liaison</title> + <para> + The XFree86 Project liaison relays information from the + XFree86 Project to the right people in the FreeBSD Project and + visa versa. This enables the projects to be alligned without + everyone in both projects staying up-to-date on the other project. + </para> + <para> + Hat currently held by: + Rich Murphey <email>rich@FreeBSD.org</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: + Steve Price <email>steve@FreeBSD.org</email>. + </para> + </section> + + <section id="role-bugmeister" xreflabel="Bugmeister"> + <title>Bugmeister</title> + <para> + The Bugmeister is person in charge of the problem report + group. + + </para> + <para> + Hat currently held by: + Giorgos Keramidas <email>keramida@FreeBSD.org</email>. + </para> + </section> + + <section id="role-donations" xreflabel="Donations Liaison Officer"> + <title>Donations Liaison Officer</title> + <para> + The task of + the donations liason officer is to match + the developers with needs with people or + organisations willing to make a + donation. The Donations Liason 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>, + currently headed by + Michael W. Lucas <email>mwlucas@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 are 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>, + currently headed by Mark Murray <email>markm@FreeBSD.org</email> + </para> + + </section> + + + + </section> + + <section> + <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 + initialise 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="figures/proc-add-committer.png" format="PNG"> + </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 8.5.8</link>. + + </para> + + <para> + <figure> + <title>Process summary: removing a committer</title> + <graphic fileref="figures/proc-rm-committer.png" format="PNG"> + </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="figures/proc-add-cvsup.png" format="PNG"> + </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> + Roles involved in this process: + <itemizedlist> + <listitem><para> + <xref linkend="tool-cvsup"> + </para></listitem> + <listitem><para> + <xref linkend="tool-ssh2"> + </para></listitem> + </itemizedlist> + </para> + + <para> + Tools used 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> + <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 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="figures/proc-commit.png" format="PNG"> + </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="figures/proc-contrib.png" format="PNG"> + </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="figures/proc-elections.png" format="PNG"> + </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> + <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. + </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ørgenssen's model for change integration</title> + <graphic fileref="figures/maintenance.png" format="PNG"> + </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 275 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="figures/proc-pr.png" format="PNG"> + </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 isn't + 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. It is not until .1 versions + are released that the branch becomes -STABLE and + -CURRENT targets the next major + version. + </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 to long with regards to security + and stability issues, + extra dicipline is required when committing changes to -STABLE. + + </para> + + + <para> + <figure> + <title>Process summary: release engineering</title> + <graphic fileref="figures/proc-releng.png" format="PNG"> + </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> + <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-cvs" xreflabel="CVS"> + <title>Concurrent Versions System (CVS)</title> + <para> + Concurrent Versions System + or simply <quote>CVS</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 is 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 + 17 general lists, 45 technical lists and 6 limited lists. 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 68 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> + <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 2003</title> + <graphic fileref="figures/portsstatus.png" format="PNG"> + </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 2003. It looks + like the curve has first grown exponentionally, and then + since the middle of 2001 grown linerly. + </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> + 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> + <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ørgensen, 2001"> + <authorgroup> + <author><firstname>Niels</firstname><surname>Jø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="bsd-hats" xreflabel="Losh, 2002"> + <authorgroup> + <author><firstname>Warner</firstname><surname>Losh</surname></author> + </authorgroup> + <copyright><year>2002</year> + <holder>The FreeBSD Documentation Project</holder> + </copyright> + <title>Working with Hats</title> + <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/hats/article.html"></ulink></bibliomisc> + </biblioentry> + + <biblioentry id="freebsd-handle-pr" xreflabel="FreeBSD, 2002C"> + <authorgroup> + <author><firstname>Dag-Erling</firstname><surname>Smø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ø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> diff --git a/en_US.ISO8859-1/books/dev-model/chapters.ent b/en_US.ISO8859-1/books/dev-model/chapters.ent new file mode 100644 index 0000000000..64d926d660 --- /dev/null +++ b/en_US.ISO8859-1/books/dev-model/chapters.ent @@ -0,0 +1,2 @@ +<!-- $FreeBSD$ --> +<!--!ENTITY chap.references SYSTEM "references.sgml"-->