diff --git a/documentation/content/en/books/design-44bsd/_index.adoc b/documentation/content/en/books/design-44bsd/_index.adoc index bc3b0057ea..289efebf32 100644 --- a/documentation/content/en/books/design-44bsd/_index.adoc +++ b/documentation/content/en/books/design-44bsd/_index.adoc @@ -1,852 +1,852 @@ --- title: The Design and Implementation of the 4.4BSD Operating System authors: - author: Marshall Kirk McKusick - author: Keith Bostic - author: Michael J. Karels - author: John S. Quarterman copyright: 1996 Addison-Wesley Longman, Inc description: Donated by Addison-Wesley, provides a design overview of 4.4BSD, from which FreeBSD was originally derived trademarks: ["design-44bsd"] bookOrder: 60 tags: ["4.4BSD", "design", "operating system", "BSD", "UNIX"] --- = The Design and Implementation of the 4.4BSD Operating System :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :sectnumoffset: 2 :source-highlighter: rouge :experimental: :images-path: books/design-44bsd/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../images/{images-path} include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' toc::[] [[overview]] == Design Overview of 4.4BSD [[overview-facilities]] === 4.4BSD Facilities and the Kernel The 4.4BSD kernel provides four basic facilities: processes, a filesystem, communications, and system startup. This section outlines where each of these four basic services is described in this book. . Processes constitute a thread of control in an address space. Mechanisms for creating, terminating, and otherwise controlling processes are described in Chapter 4. The system multiplexes separate virtual-address spaces for each process; this memory management is discussed in Chapter 5. . The user interface to the filesystem and devices is similar; common aspects are discussed in Chapter 6. The filesystem is a set of named files, organized in a tree-structured hierarchy of directories, and of operations to manipulate them, as presented in Chapter 7. Files reside on physical media such as disks. 4.4BSD supports several organizations of data on the disk, as set forth in Chapter 8. Access to files on remote machines is the subject of Chapter 9. Terminals are used to access the system; their operation is the subject of Chapter 10. . Communication mechanisms provided by traditional UNIX systems include simplex reliable byte streams between related processes (see pipes, Section 11.1), and notification of exceptional events (see signals, Section 4.7). 4.4BSD also has a general interprocess-communication facility. This facility, described in Chapter 11, uses access mechanisms distinct from those of the filesystem, but, once a connection is set up, a process can access it as though it were a pipe. There is a general networking framework, discussed in Chapter 12, that is normally used as a layer underlying the IPC facility. Chapter 13 describes a particular networking implementation in detail. . Any real operating system has operational issues, such as how to start it running. Startup and operational issues are described in Chapter 14. Sections 2.3 through 2.14 present introductory material related to Chapters 3 through 14. We shall define terms, mention basic system calls, and explore historical developments. Finally, we shall give the reasons for many major design decisions. ==== The Kernel The _kernel_ is the part of the system that runs in protected mode and mediates access by all user programs to the underlying hardware (e.g., CPU, disks, terminals, network links) and software constructs (e.g., filesystem, network protocols). The kernel provides the basic system facilities; it creates and manages processes, and provides functions to access the filesystem and communication facilities. These functions, called _system calls_ appear to user processes as library subroutines. These system calls are the only interface that processes have to these facilities. Details of the system-call mechanism are given in Chapter 3, as are descriptions of several kernel mechanisms that do not execute as the direct result of a process doing a system call. A _kernel_ in traditional operating-system terminology, is a small nucleus of software that provides only the minimal facilities necessary for implementing additional operating-system services. In contemporary research operating systems -- such as Chorus <>, Mach <>, Tunis <>, and the V Kernel <> -- this division of functionality is more than just a logical one. Services such as filesystems and networking protocols are implemented as client application processes of the nucleus or kernel. The 4.4BSD kernel is not partitioned into multiple processes. This basic design decision was made in the earliest versions of UNIX. The first two implementations by Ken Thompson had no memory mapping, and thus made no hardware-enforced distinction between user and kernel space <>. A message-passing system could have been implemented as readily as the actually implemented model of kernel and user processes. The monolithic kernel was chosen for simplicity and performance. And the early kernels were small; the inclusion of facilities such as networking into the kernel has increased its size. The current trend in operating-systems research is to reduce the kernel size by placing such services in user space. Users ordinarily interact with the system through a command-language interpreter, called a _shell_, and perhaps through additional user application programs. Such programs and the shell are implemented with processes. Details of such programs are beyond the scope of this book, which instead concentrates almost exclusively on the kernel. Sections 2.3 and 2.4 describe the services provided by the 4.4BSD kernel, and give an overview of the latter's design. Later chapters describe the detailed design and implementation of these services as they appear in 4.4BSD. [[overview-kernel-organization]] === Kernel Organization In this section, we view the organization of the 4.4BSD kernel in two ways: [arabic] . As a static body of software, categorized by the functionality offered by the modules that make up the kernel . By its dynamic operation, categorized according to the services provided to users The largest part of the kernel implements the system services that applications access through system calls. In 4.4BSD, this software has been organized according to the following: * Basic kernel facilities: timer and system-clock handling, descriptor management, and process management * Memory-management support: paging and swapping * Generic system interfaces: the I/O, control, and multiplexing operations performed on descriptors * The filesystem: files, directories, pathname translation, file locking, and I/O buffer management * Terminal-handling support: the terminal-interface driver and terminal line disciplines * Interprocess-communication facilities: sockets * Support for network communication: communication protocols and generic network facilities, such as routing .Machine-independent software in the 4.4BSD kernel [[table-mach-indep]] [cols=",,",options="header",] |=== |Category |Lines of code |Percentage of kernel |headers |9,393 |4.6 |initialization |1,107 |0.6 |kernel facilities |8,793 |4.4 |generic interfaces |4,782 |2.4 |interprocess communication |4,540 |2.2 |terminal handling |3,911 |1.9 |virtual memory |11,813 |5.8 |vnode management |7,954 |3.9 |filesystem naming |6,550 |3.2 |fast filestore |4,365 |2.2 |log-structure filestore |4,337 |2.1 |memory-based filestore |645 |0.3 |cd9660 filesystem |4,177 |2.1 |miscellaneous filesystems (10) |12,695 |6.3 |network filesystem |17,199 |8.5 |network communication |8,630 |4.3 |internet protocols |11,984 |5.9 |ISO protocols |23,924 |11.8 |X.25 protocols |10,626 |5.3 |XNS protocols |5,192 |2.6 |=== Most of the software in these categories is machine independent and is portable across different hardware architectures. The machine-dependent aspects of the kernel are isolated from the mainstream code. In particular, none of the machine-independent code contains conditional code for specific architecture. When an architecture-dependent action is needed, the machine-independent code calls an architecture-dependent function that is located in the machine-dependent code. The software that is machine dependent includes * Low-level system-startup actions * Trap and fault handling * Low-level manipulation of the run-time context of a process * Configuration and initialization of hardware devices * Run-time support for I/O devices .Machine-dependent software for the HP300 in the 4.4BSD kernel [[table-mach-dep]] [cols=",,",options="header",] |=== |Category |Lines of code |Percentage of kernel |machine dependent headers |1,562 |0.8 |device driver headers |3,495 |1.7 |device driver source |17,506 |8.7 |virtual memory |3,087 |1.5 |other machine dependent |6,287 |3.1 |routines in assembly language |3,014 |1.5 |HP/UX compatibility |4,683 |2.3 |=== <> summarizes the machine-independent software that constitutes the 4.4BSD kernel for the HP300. The numbers in column 2 are for lines of C source code, header files, and assembly language. Virtually all the software in the kernel is written in the C programming language; less than 2 percent is written in assembly language. As the statistics in <> show, the machine-dependent software, excluding HP/UX and device support, accounts for a minuscule 6.9 percent of the kernel. Only a small part of the kernel is devoted to initializing the system. This code is used when the system is _bootstrapped_ into operation and is responsible for setting up the kernel hardware and software environment (see Chapter 14). Some operating systems (especially those with limited physical memory) discard or _overlay_ the software that performs these functions after that software has been executed. The 4.4BSD kernel does not reclaim the memory used by the startup code because that memory space is barely 0.5 percent of the kernel resources used on a typical machine. Also, the startup code does not appear in one place in the kernel -- it is scattered throughout, and it usually appears in places logically associated with what is being initialized. [[overview-kernel-service]] === Kernel Services The boundary between the kernel- and user-level code is enforced by hardware-protection facilities provided by the underlying hardware. The kernel operates in a separate address space that is inaccessible to user processes. Privileged operations -- such as starting I/O and halting the central processing unit (CPU) -- are available to only the kernel. Applications request services from the kernel with _system calls_. System calls are used to cause the kernel to execute complicated operations, such as writing data to secondary storage, and simple operations, such as returning the current time of day. All system calls appear _synchronous_ to applications: The application does not run while the kernel does the actions associated with a system call. The kernel may finish some operations associated with a system call after it has returned. For example, a _write_ system call will copy the data to be written from the user process to a kernel buffer while the process waits, but will usually return from the system call before the kernel buffer is written to the disk. A system call usually is implemented as a hardware trap that changes the CPU's execution mode and the current address-space mapping. Parameters supplied by users in system calls are validated by the kernel before being used. Such checking ensures the integrity of the system. All parameters passed into the kernel are copied into the kernel's address space, to ensure that validated parameters are not changed as a side effect of the system call. System-call results are returned by the kernel, either in hardware registers or by their values being copied to user-specified memory addresses. Like parameters passed into the kernel, addresses used for the return of results must be validated to ensure that they are part of an application's address space. If the kernel encounters an error while processing a system call, it returns an error code to the user. For the C programming language, this error code is stored in the global variable _errno_, and the function that executed the system call returns the value -1. User applications and the kernel operate independently of each other. 4.4BSD does not store I/O control blocks or other operating-system-related data structures in the application's address space. Each user-level application is provided an independent address space in which it executes. The kernel makes most state changes, such as suspending a process while another is running, invisible to the processes involved. [[overview-process-management]] === Process Management 4.4BSD supports a multitasking environment. Each task or thread of execution is termed a _process_. The _context_ of a 4.4BSD process consists of user-level state, including the contents of its address space and the run-time environment, and kernel-level state, which includes scheduling parameters, resource controls, and identification information. The context includes everything used by the kernel in providing services for the process. Users can create processes, control the processes' execution, and receive notification when the processes' execution status changes. Every process is assigned a unique value, termed a _process identifier_ (PID). This value is used by the kernel to identify a process when reporting status changes to a user, and by a user when referencing a process in a system call. The kernel creates a process by duplicating the context of another process. The new process is termed a _child process_ of the original _parent process_ The context duplicated in process creation includes both the user-level execution state of the process and the process's system state managed by the kernel. Important components of the kernel state are described in Chapter 4. [[fig-process-lifecycle]] .Process lifecycle image:fig1.png[Process lifecycle] The process lifecycle is depicted in <>. A process may create a new process that is a copy of the original by using the _fork_ system call. The _fork_ call returns twice: once in the parent process, where the return value is the process identifier of the child, and once in the child process, where the return value is 0. The parent-child relationship induces a hierarchical structure on the set of processes in the system. The new process shares all its parent's resources, such as file descriptors, signal-handling status, and memory layout. Although there are occasions when the new process is intended to be a copy of the parent, the loading and execution of a different program is a more useful and typical action. A process can overlay itself with the memory image of another program, passing to the newly created image a set of parameters, using the system call _execve_. One parameter is the name of a file whose contents are in a format recognized by the system -- either a binary-executable file or a file that causes the execution of a specified interpreter program to process its contents. A process may terminate by executing an _exit_ system call, sending 8 bits of exit status to its parent. If a process wants to communicate more than a single byte of information with its parent, it must either set up an interprocess-communication channel using pipes or sockets, or use an intermediate file. Interprocess communication is discussed extensively in Chapter 11. A process can suspend execution until any of its child processes terminate using the _wait_ system call, which returns the PID and exit status of the terminated child process. A parent process can arrange to be notified by a signal when a child process exits or terminates abnormally. Using the _wait4_ system call, the parent can retrieve information about the event that caused termination of the child process and about resources consumed by the process during its lifetime. If a process is orphaned because its parent exits before it is finished, then the kernel arranges for the child's exit status to be passed back to a special system process _init_: see Sections 3.1 and 14.6). The details of how the kernel creates and destroys processes are given in Chapter 5. Processes are scheduled for execution according to a _process-priority_ parameter. This priority is managed by a kernel-based scheduling algorithm. Users can influence the scheduling of a process by specifying a parameter (_nice_) that weights the overall scheduling priority, but are still obligated to share the underlying CPU resources according to the kernel's scheduling policy. ==== Signals The system defines a set of _signals_ that may be delivered to a process. Signals in 4.4BSD are modeled after hardware interrupts. A process may specify a user-level subroutine to be a _handler_ to which a signal should be delivered. When a signal is generated, it is blocked from further occurrence while it is being _caught_ by the handler. Catching a signal involves saving the current process context and building a new one in which to run the handler. The signal is then delivered to the handler, which can either abort the process or return to the executing process (perhaps after setting a global variable). If the handler returns, the signal is unblocked and can be generated (and caught) again. Alternatively, a process may specify that a signal is to be _ignored_, or that a default action, as determined by the kernel, is to be taken. The default action of certain signals is to terminate the process. This termination may be accompanied by creation of a _core file_ that contains the current memory image of the process for use in postmortem debugging. Some signals cannot be caught or ignored. These signals include _SIGKILL_, which kills runaway processes, and the job-control signal _SIGSTOP_. A process may choose to have signals delivered on a special stack so that sophisticated software stack manipulations are possible. For example, a language supporting coroutines needs to provide a stack for each coroutine. The language run-time system can allocate these stacks by dividing up the single stack provided by 4.4BSD. If the kernel does not support a separate signal stack, the space allocated for each coroutine must be expanded by the amount of space required to catch a signal. All signals have the same _priority_. If multiple signals are pending simultaneously, the order in which signals are delivered to a process is implementation specific. Signal handlers execute with the signal that caused their invocation to be blocked, but other signals may yet occur. Mechanisms are provided so that processes can protect critical sections of code against the occurrence of specified signals. The detailed design and implementation of signals is described in Section 4.7. ==== Process Groups and Sessions Processes are organized into _process groups_. Process groups are used to control access to terminals and to provide a means of distributing signals to collections of related processes. A process inherits its process group from its parent process. Mechanisms are provided by the kernel to allow a process to alter its process group or the process group of its descendents. Creating a new process group is easy; the value of a new process group is ordinarily the process identifier of the creating process. The group of processes in a process group is sometimes referred to as a _job_ and is manipulated by high-level system software, such as the shell. A common kind of job created by a shell is a _pipeline_ of several processes connected by pipes, such that the output of the first process is the input of the second, the output of the second is the input of the third, and so forth. The shell creates such a job by forking a process for each stage of the pipeline, then putting all those processes into a separate process group. A user process can send a signal to each process in a process group, as well as to a single process. A process in a specific process group may receive software interrupts affecting the group, causing the group to suspend or resume execution, or to be interrupted or terminated. A terminal has a process-group identifier assigned to it. This identifier is normally set to the identifier of a process group associated with the terminal. A job-control shell may create a number of process groups associated with the same terminal; the terminal is the _controlling terminal_ for each process in these groups. A process may read from a descriptor for its controlling terminal only if the terminal's process-group identifier matches that of the process. If the identifiers do not match, the process will be blocked if it attempts to read from the terminal. By changing the process-group identifier of the terminal, a shell can arbitrate a terminal among several different jobs. This arbitration is called _job control_ and is described, with process groups, in Section 4.8. Just as a set of related processes can be collected into a process group, a set of process groups can be collected into a _session_. -The main uses for sessions are to create an isolated environment for a daemon process and its children, and to collect together a user's login shell and the jobs that that shell spawns. +The main uses for sessions are to create an isolated environment for a daemon process and its children, and to collect together a user's login shell and the jobs that shell spawns. [[overview-memory-management]] === Memory Management Each process has its own private address space. The address space is initially divided into three logical segments: _text_, _data_, and _stack_. The text segment is read-only and contains the machine instructions of a program. The data and stack segments are both readable and writable. The data segment contains the initialized and uninitialized data portions of a program, whereas the stack segment holds the application's run-time stack. On most machines, the stack segment is extended automatically by the kernel as the process executes. A process can expand or contract its data segment by making a system call, whereas a process can change the size of its text segment only when the segment's contents are overlaid with data from the filesystem, or when debugging takes place. The initial contents of the segments of a child process are duplicates of the segments of a parent process. The entire contents of a process address space do not need to be resident for a process to execute. If a process references a part of its address space that is not resident in main memory, the system _pages_ the necessary information into memory. When system resources are scarce, the system uses a two-level approach to maintain available resources. If a modest amount of memory is available, the system will take memory resources away from processes if these resources have not been used recently. Should there be a severe resource shortage, the system will resort to _swapping_ the entire context of a process to secondary storage. The _demand paging_ and _swapping_ done by the system are effectively transparent to processes. A process may, however, advise the system about expected future memory utilization as a performance aid. ==== BSD Memory-Management Design Decisions The support of large sparse address spaces, mapped files, and shared memory was a requirement for 4.2BSD. An interface was specified, called _mmap_, that allowed unrelated processes to request a shared mapping of a file into their address spaces. If multiple processes mapped the same file into their address spaces, changes to the file's portion of an address space by one process would be reflected in the area mapped by the other processes, as well as in the file itself. Ultimately, 4.2BSD was shipped without the _mmap_ interface, because of pressure to make other features, such as networking, available. Further development of the _mmap_ interface continued during the work on 4.3BSD. Over 40 companies and research groups participated in the discussions leading to the revised architecture that was described in the Berkeley Software Architecture Manual <>. Several of the companies have implemented the revised interface <>. Once again, time pressure prevented 4.3BSD from providing an implementation of the interface. Although the latter could have been built into the existing 4.3BSD virtual-memory system, the developers decided not to put it in because that implementation was nearly 10 years old. Furthermore, the original virtual-memory design was based on the assumption that computer memories were small and expensive, whereas disks were locally connected, fast, large, and inexpensive. Thus, the virtual-memory system was designed to be frugal with its use of memory at the expense of generating extra disk traffic. In addition, the 4.3BSD implementation was riddled with VAX memory-management hardware dependencies that impeded its portability to other computer architectures. Finally, the virtual-memory system was not designed to support the tightly coupled multiprocessors that are becoming increasingly common and important today. Attempts to improve the old implementation incrementally seemed doomed to failure. A completely new design, on the other hand, could take advantage of large memories, conserve disk transfers, and have the potential to run on multiprocessors. Consequently, the virtual-memory system was completely replaced in 4.4BSD. The 4.4BSD virtual-memory system is based on the Mach 2.0 VM system <>. with updates from Mach 2.5 and Mach 3.0. It features efficient support for sharing, a clean separation of machine-independent and machine-dependent features, as well as (currently unused) multiprocessor support. Processes can map files anywhere in their address space. They can share parts of their address space by doing a shared mapping of the same file. Changes made by one process are visible in the address space of the other process, and also are written back to the file itself. Processes can also request private mappings of a file, which prevents any changes that they make from being visible to other processes mapping the file or being written back to the file itself. Another issue with the virtual-memory system is the way that information is passed into the kernel when a system call is made. 4.4BSD always copies data from the process address space into a buffer in the kernel. For read or write operations that are transferring large quantities of data, doing the copy can be time consuming. An alternative to doing the copying is to remap the process memory into the kernel. The 4.4BSD kernel always copies the data for several reasons: * Often, the user data are not page aligned and are not a multiple of the hardware page length. * If the page is taken away from the process, it will no longer be able to reference that page. Some programs depend on the data remaining in the buffer even after those data have been written. * If the process is allowed to keep a copy of the page (as it is in current 4.4BSD semantics), the page must be made _copy-on-write_. A copy-on-write page is one that is protected against being written by being made read-only. If the process attempts to modify the page, the kernel gets a write fault. The kernel then makes a copy of the page that the process can modify. Unfortunately, the typical process will immediately try to write new data to its output buffer, forcing the data to be copied anyway. * When pages are remapped to new virtual-memory addresses, most memory-management hardware requires that the hardware address-translation cache be purged selectively. The cache purges are often slow. The net effect is that remapping is slower than copying for blocks of data less than 4 to 8 Kbyte. The biggest incentives for memory mapping are the needs for accessing big files and for passing large quantities of data between processes. The _mmap_ interface provides a way for both of these tasks to be done without copying. ==== Memory Management Inside the Kernel The kernel often does allocations of memory that are needed for only the duration of a single system call. In a user process, such short-term memory would be allocated on the run-time stack. Because the kernel has a limited run-time stack, it is not feasible to allocate even moderate-sized blocks of memory on it. Consequently, such memory must be allocated through a more dynamic mechanism. For example, when the system must translate a pathname, it must allocate a 1-Kbyte buffer to hold the name. Other blocks of memory must be more persistent than a single system call, and thus could not be allocated on the stack even if there was space. An example is protocol-control blocks that remain throughout the duration of a network connection. Demands for dynamic memory allocation in the kernel have increased as more services have been added. A generalized memory allocator reduces the complexity of writing code inside the kernel. Thus, the 4.4BSD kernel has a single memory allocator that can be used by any part of the system. It has an interface similar to the C library routines _malloc_ and _free_ that provide memory allocation to application programs <>. Like the C library interface, the allocation routine takes a parameter specifying the size of memory that is needed. The range of sizes for memory requests is not constrained; however, physical memory is allocated and is not paged. The free routine takes a pointer to the storage being freed, but does not require the size of the piece of memory being freed. [[overview-io-system]] === I/O System The basic model of the UNIX I/O system is a sequence of bytes that can be accessed either randomly or sequentially. There are no _access methods_ and no _control blocks_ in a typical UNIX user process. Different programs expect various levels of structure, but the kernel does not impose structure on I/O. For instance, the convention for text files is lines of ASCII characters separated by a single newline character (the ASCII line-feed character), but the kernel knows nothing about this convention. For the purposes of most programs, the model is further simplified to being a stream of data bytes, or an _I/O stream_. It is this single common data form that makes the characteristic UNIX tool-based approach work <>. An I/O stream from one program can be fed as input to almost any other program. (This kind of traditional UNIX I/O stream should not be confused with the Eighth Edition stream I/O system or with the System V, Release 3 STREAMS, both of which can be accessed as traditional I/O streams.) ==== Descriptors and I/O UNIX processes use _descriptors_ to reference I/O streams. Descriptors are small unsigned integers obtained from the _open_ and _socket_ system calls. The _open_ system call takes as arguments the name of a file and a permission mode to specify whether the file should be open for reading or for writing, or for both. This system call also can be used to create a new, empty file. A _read_ or _write_ system call can be applied to a descriptor to transfer data. The _close_ system call can be used to deallocate any descriptor. Descriptors represent underlying objects supported by the kernel, and are created by system calls specific to the type of object. In 4.4BSD, three kinds of objects can be represented by descriptors: files, pipes, and sockets. * A _file_ is a linear array of bytes with at least one name. A file exists until all its names are deleted explicitly and no process holds a descriptor for it. A process acquires a descriptor for a file by opening that file's name with the _open_ system call. I/O devices are accessed as files. * A _pipe_ is a linear array of bytes, as is a file, but it is used solely as an I/O stream, and it is unidirectional. It also has no name, and thus cannot be opened with _open_. Instead, it is created by the _pipe_ system call, which returns two descriptors, one of which accepts input that is sent to the other descriptor reliably, without duplication, and in order. The system also supports a named pipe or FIFO. A FIFO has properties identical to a pipe, except that it appears in the filesystem; thus, it can be opened using the _open_ system call. Two processes that wish to communicate each open the FIFO: One opens it for reading, the other for writing. * A _socket_ is a transient object that is used for interprocess communication; it exists only as long as some process holds a descriptor referring to it. A socket is created by the _socket_ system call, which returns a descriptor for it. There are different kinds of sockets that support various communication semantics, such as reliable delivery of data, preservation of message ordering, and preservation of message boundaries. In systems before 4.2BSD, pipes were implemented using the filesystem; when sockets were introduced in 4.2BSD, pipes were reimplemented as sockets. The kernel keeps for each process a _descriptor table_, which is a table that the kernel uses to translate the external representation of a descriptor into an internal representation. (The descriptor is merely an index into this table.) The descriptor table of a process is inherited from that process's parent, and thus access to the objects to which the descriptors refer also is inherited. The main ways that a process can obtain a descriptor are by opening or creation of an object, and by inheritance from the parent process. In addition, socket IPC allows passing of descriptors in messages between unrelated processes on the same machine. Every valid descriptor has an associated _file offset_ in bytes from the beginning of the object. Read and write operations start at this offset, which is updated after each data transfer. For objects that permit random access, the file offset also may be set with the _lseek_ system call. Ordinary files permit random access, and some devices do, as well. Pipes and sockets do not. When a process terminates, the kernel reclaims all the descriptors that were in use by that process. If the process was holding the final reference to an object, the object's manager is notified so that it can do any necessary cleanup actions, such as final deletion of a file or deallocation of a socket. ==== Descriptor Management Most processes expect three descriptors to be open already when they start running. These descriptors are 0, 1, 2, more commonly known as _standard input_, _standard output_, and _standard error_, respectively. Usually, all three are associated with the user's terminal by the login process (see Section 14.6) and are inherited through _fork_ and _exec_ by processes run by the user. Thus, a program can read what the user types by reading standard input, and the program can send output to the user's screen by writing to standard output. The standard error descriptor also is open for writing and is used for error output, whereas standard output is used for ordinary output. These (and other) descriptors can be mapped to objects other than the terminal; such mapping is called _I/O redirection_, and all the standard shells permit users to do it. The shell can direct the output of a program to a file by closing descriptor 1 (standard output) and opening the desired output file to produce a new descriptor 1. It can similarly redirect standard input to come from a file by closing descriptor 0 and opening the file. Pipes allow the output of one program to be input to another program without rewriting or even relinking of either program. Instead of descriptor 1 (standard output) of the source program being set up to write to the terminal, it is set up to be the input descriptor of a pipe. Similarly, descriptor 0 (standard input) of the sink program is set up to reference the output of the pipe, instead of the terminal keyboard. The resulting set of two processes and the connecting pipe is known as a _pipeline_. Pipelines can be arbitrarily long series of processes connected by pipes. The _open_, _pipe_, and _socket_ system calls produce new descriptors with the lowest unused number usable for a descriptor. For pipelines to work, some mechanism must be provided to map such descriptors into 0 and 1. The _dup_ system call creates a copy of a descriptor that points to the same file-table entry. The new descriptor is also the lowest unused one, but if the desired descriptor is closed first, _dup_ can be used to do the desired mapping. Care is required, however: If descriptor 1 is desired, and descriptor 0 happens also to have been closed, descriptor 0 will be the result. To avoid this problem, the system provides the _dup2_ system call; it is like _dup_, but it takes an additional argument specifying the number of the desired descriptor (if the desired descriptor was already open, _dup2_ closes it before reusing it). ==== Devices Hardware devices have filenames, and may be accessed by the user via the same system calls used for regular files. The kernel can distinguish a _device special file_ or _special file_, and can determine to what device it refers, but most processes do not need to make this determination. Terminals, printers, and tape drives are all accessed as though they were streams of bytes, like 4.4BSD disk files. Thus, device dependencies and peculiarities are kept in the kernel as much as possible, and even in the kernel most of them are segregated in the device drivers. Hardware devices can be categorized as either _structured_ or _unstructured_; they are known as _block_ or _character_ devices, respectively. Processes typically access devices through _special files_ in the filesystem. I/O operations to these files are handled by kernel-resident software modules termed _device drivers_. Most network-communication hardware devices are accessible through only the interprocess-communication facilities, and do not have special files in the filesystem name space, because the _raw-socket_ interface provides a more natural interface than does a special file. Structured or block devices are typified by disks and magnetic tapes, and include most random-access devices. The kernel supports read-modify-write-type buffering actions on block-oriented structured devices to allow the latter to be read and written in a totally random byte-addressed fashion, like regular files. Filesystems are created on block devices. Unstructured devices are those devices that do not support a block structure. Familiar unstructured devices are communication lines, raster plotters, and unbuffered magnetic tapes and disks. Unstructured devices typically support large block I/O transfers. Unstructured files are called _character devices_ because the first of these to be implemented were terminal device drivers. The kernel interface to the driver for these devices proved convenient for other devices that were not block structured. Device special files are created by the _mknod_ system call. There is an additional system call, _ioctl_, for manipulating the underlying device parameters of special files. The operations that can be done differ for each device. This system call allows the special characteristics of devices to be accessed, rather than overloading the semantics of other system calls. For example, there is an _ioctl_ on a tape drive to write an end-of-tape mark, instead of there being a special or modified version of _write_. ==== Socket IPC The 4.2BSD kernel introduced an IPC mechanism more flexible than pipes, based on _sockets_. A socket is an endpoint of communication referred to by a descriptor, just like a file or a pipe. Two processes can each create a socket, and then connect those two endpoints to produce a reliable byte stream. Once connected, the descriptors for the sockets can be read or written by processes, just as the latter would do with a pipe. The transparency of sockets allows the kernel to redirect the output of one process to the input of another process residing on another machine. A major difference between pipes and sockets is that pipes require a common parent process to set up the communications channel. A connection between sockets can be set up by two unrelated processes, possibly residing on different machines. System V provides local interprocess communication through FIFOs (also known as _named pipes_). FIFOs appear as an object in the filesystem that unrelated processes can open and send data through in the same way as they would communicate through a pipe. Thus, FIFOs do not require a common parent to set them up; they can be connected after a pair of processes are up and running. Unlike sockets, FIFOs can be used on only a local machine; they cannot be used to communicate between processes on different machines. FIFOs are implemented in 4.4BSD only because they are required by the POSIX.1 standard. Their functionality is a subset of the socket interface. The socket mechanism requires extensions to the traditional UNIX I/O system calls to provide the associated naming and connection semantics. Rather than overloading the existing interface, the developers used the existing interfaces to the extent that the latter worked without being changed, and designed new interfaces to handle the added semantics. The _read_ and _write_ system calls were used for byte-stream type connections, but six new system calls were added to allow sending and receiving addressed messages such as network datagrams. The system calls for writing messages include _send_, _sendto_, and _sendmsg_. The system calls for reading messages include _recv_, _recvfrom_, and _recvmsg_. In retrospect, the first two in each class are special cases of the others; _recvfrom_ and _sendto_ probably should have been added as library interfaces to _recvmsg_ and _sendmsg_, respectively. ==== Scatter/Gather I/O In addition to the traditional _read_ and _write_ system calls, 4.2BSD introduced the ability to do scatter/gather I/O. Scatter input uses the _readv_ system call to allow a single read to be placed in several different buffers. Conversely, the _writev_ system call allows several different buffers to be written in a single atomic write. Instead of passing a single buffer and length parameter, as is done with _read_ and _write_, the process passes in a pointer to an array of buffers and lengths, along with a count describing the size of the array. This facility allows buffers in different parts of a process address space to be written atomically, without the need to copy them to a single contiguous buffer. Atomic writes are necessary in the case where the underlying abstraction is record based, such as tape drives that output a tape block on each write request. It is also convenient to be able to read a single request into several different buffers (such as a record header into one place and the data into another). Although an application can simulate the ability to scatter data by reading the data into a large buffer and then copying the pieces to their intended destinations, the cost of memory-to-memory copying in such cases often would more than double the running time of the affected application. Just as _send_ and _recv_ could have been implemented as library interfaces to _sendto_ and _recvfrom_, it also would have been possible to simulate _read_ with _readv_ and _write_ with _writev_. However, _read_ and _write_ are used so much more frequently that the added cost of simulating them would not have been worthwhile. ==== Multiple Filesystem Support With the expansion of network computing, it became desirable to support both local and remote filesystems. To simplify the support of multiple filesystems, the developers added a new virtual node or _vnode_ interface to the kernel. The set of operations exported from the vnode interface appear much like the filesystem operations previously supported by the local filesystem. However, they may be supported by a wide range of filesystem types: * Local disk-based filesystems * Files imported using a variety of remote filesystem protocols * Read-only CD-ROM filesystems * Filesystems providing special-purpose interfaces -- for example, the `/proc` filesystem A few variants of 4.4BSD, such as FreeBSD, allow filesystems to be loaded dynamically when the filesystems are first referenced by the _mount_ system call. The vnode interface is described in Section 6.5; its ancillary support routines are described in Section 6.6; several of the special-purpose filesystems are described in Section 6.7. [[overview-filesystem]] === Filesystems A regular file is a linear array of bytes, and can be read and written starting at any byte in the file. The kernel distinguishes no record boundaries in regular files, although many programs recognize line-feed characters as distinguishing the ends of lines, and other programs may impose other structure. No system-related information about a file is kept in the file itself, but the filesystem stores a small amount of ownership, protection, and usage information with each file. A _filename_ component is a string of up to 255 characters. These filenames are stored in a type of file called a _directory_. The information in a directory about a file is called a _directory entry_ and includes, in addition to the filename, a pointer to the file itself. Directory entries may refer to other directories, as well as to plain files. A hierarchy of directories and files is thus formed, and is called a _filesystem_; .A small filesystem [[fig-small-fs]] image:fig2.png[A small filesystem] a small one is shown in <>. Directories may contain subdirectories, and there is no inherent limitation to the depth with which directory nesting may occur. To protect the consistency of the filesystem, the kernel does not permit processes to write directly into directories. A filesystem may include not only plain files and directories, but also references to other objects, such as devices and sockets. The filesystem forms a tree, the beginning of which is the _root directory_, sometimes referred to by the name _slash_, spelled with a single solidus character (/). The root directory contains files; in our example in Fig 2.2, it contains `vmunix`, a copy of the kernel-executable object file. It also contains directories; in this example, it contains the `usr` directory. Within the `usr` directory is the `bin` directory, which mostly contains executable object code of programs, such as the files `ls` and `vi`. A process identifies a file by specifying that file's _pathname_, which is a string composed of zero or more filenames separated by slash (/) characters. The kernel associates two directories with each process for use in interpreting pathnames. A process's _root directory_ is the topmost point in the filesystem that the process can access; it is ordinarily set to the root directory of the entire filesystem. A pathname beginning with a slash is called an _absolute pathname_, and is interpreted by the kernel starting with the process's root directory. A pathname that does not begin with a slash is called a _relative pathname_, and is interpreted relative to the _current working directory_ of the process. (This directory also is known by the shorter names _current directory_ or _working directory_.) The current directory itself may be referred to directly by the name _dot_, spelled with a single period (`.`) The filename _dot-dot_ (`..`) refers to a directory's parent directory. The root directory is its own parent. A process may set its root directory with the _chroot_ system call, and its current directory with the _chdir_ system call. Any process may do _chdir_ at any time, but _chroot_ is permitted only a process with superuser privileges. _Chroot_ is normally used to set up restricted access to the system. Using the filesystem shown in Fig. 2.2, if a process has the root of the filesystem as its root directory, and has `/usr` as its current directory, it can refer to the file `vi` either from the root with the absolute pathname `/usr/bin/vi`, or from its current directory with the relative pathname `bin/vi`. System utilities and databases are kept in certain well-known directories. Part of the well-defined hierarchy includes a directory that contains the _home directory_ for each user -- for example, `/usr/staff/mckusick` and `/usr/staff/karels` in Fig. 2.2. When users log in, the current working directory of their shell is set to the home directory. Within their home directories, users can create directories as easily as they can regular files. Thus, a user can build arbitrarily complex subhierarchies. The user usually knows of only one filesystem, but the system may know that this one virtual filesystem is really composed of several physical filesystems, each on a different device. A physical filesystem may not span multiple hardware devices. Since most physical disk devices are divided into several logical devices, there may be more than one filesystem per physical device, but there will be no more than one per logical device. One filesystem -- the filesystem that anchors all absolute pathnames -- is called the _root filesystem_, and is always available. Others may be mounted; that is, they may be integrated into the directory hierarchy of the root filesystem. References to a directory that has a filesystem mounted on it are converted transparently by the kernel into references to the root directory of the mounted filesystem. The _link_ system call takes the name of an existing file and another name to create for that file. After a successful _link_, the file can be accessed by either filename. A filename can be removed with the _unlink_ system call. When the final name for a file is removed (and the final process that has the file open closes it), the file is deleted. Files are organized hierarchically in _directories_. A directory is a type of file, but, in contrast to regular files, a directory has a structure imposed on it by the system. A process can read a directory as it would an ordinary file, but only the kernel is permitted to modify a directory. Directories are created by the _mkdir_ system call and are removed by the _rmdir_ system call. Before 4.2BSD, the _mkdir_ and _rmdir_ system calls were implemented by a series of _link_ and _unlink_ system calls being done. There were three reasons for adding systems calls explicitly to create and delete directories: [arabic] . The operation could be made atomic. If the system crashed, the directory would not be left half-constructed, as could happen when a series of link operations were used. . When a networked filesystem is being run, the creation and deletion of files and directories need to be specified atomically so that they can be serialized. . When supporting non-UNIX filesystems, such as an MS-DOS filesystem, on another partition of the disk, the other filesystem may not support link operations. Although other filesystems might support the concept of directories, they probably would not create and delete the directories with links, as the UNIX filesystem does. Consequently, they could create and delete directories only if explicit directory create and delete requests were presented. The _chown_ system call sets the owner and group of a file, and _chmod_ changes protection attributes. _Stat_ applied to a filename can be used to read back such properties of a file. The _fchown_, _fchmod_, and _fstat_ system calls are applied to a descriptor, instead of to a filename, to do the same set of operations. The _rename_ system call can be used to give a file a new name in the filesystem, replacing one of the file's old names. Like the directory-creation and directory-deletion operations, the _rename_ system call was added to 4.2BSD to provide atomicity to name changes in the local filesystem. Later, it proved useful explicitly to export renaming operations to foreign filesystems and over the network. The _truncate_ system call was added to 4.2BSD to allow files to be shortened to an arbitrary offset. The call was added primarily in support of the Fortran run-time library, which has the semantics such that the end of a random-access file is set to be wherever the program most recently accessed that file. Without the _truncate_ system call, the only way to shorten a file was to copy the part that was desired to a new file, to delete the old file, then to rename the copy to the original name. As well as this algorithm being slow, the library could potentially fail on a full filesystem. Once the filesystem had the ability to shorten files, the kernel took advantage of that ability to shorten large empty directories. The advantage of shortening empty directories is that it reduces the time spent in the kernel searching them when names are being created or deleted. Newly created files are assigned the user identifier of the process that created them and the group identifier of the directory in which they were created. A three-level access-control mechanism is provided for the protection of files. These three levels specify the accessibility of a file to [arabic] . The user who owns the file . The group that owns the file . Everyone else Each level of access has separate indicators for read permission, write permission, and execute permission. Files are created with zero length, and may grow when they are written. While a file is open, the system maintains a pointer into the file indicating the current location in the file associated with the descriptor. This pointer can be moved about in the file in a random-access fashion. Processes sharing a file descriptor through a _fork_ or _dup_ system call share the current location pointer. Descriptors created by separate _open_ system calls have separate current location pointers. Files may have _holes_ in them. Holes are void areas in the linear extent of the file where data have never been written. A process can create these holes by positioning the pointer past the current end-of-file and writing. When read, holes are treated by the system as zero-valued bytes. Earlier UNIX systems had a limit of 14 characters per filename component. This limitation was often a problem. For example, in addition to the natural desire of users to give files long descriptive names, a common way of forming filenames is as `basename.extension`, where the extension (indicating the kind of file, such as `.c` for C source or `.o` for intermediate binary object) is one to three characters, leaving 10 to 12 characters for the basename. Source-code-control systems and editors usually take up another two characters, either as a prefix or a suffix, for their purposes, leaving eight to 10 characters. It is easy to use 10 or 12 characters in a single English word as a basename (e.g., `multiplexer`). It is possible to keep within these limits, but it is inconvenient or even dangerous, because other UNIX systems accept strings longer than the limit when creating files, but then _truncate_ to the limit. A C language source file named `multiplexer.c` (already 13 characters) might have a source-code-control file with `s.` prepended, producing a filename `s.multiplexer` that is indistinguishable from the source-code-control file for `multiplexer.ms`, a file containing `troff` source for documentation for the C program. The contents of the two original files could easily get confused with no warning from the source-code-control system. Careful coding can detect this problem, but the long filenames first introduced in 4.2BSD practically eliminate it. [[overview-filestore]] === Filestores The operations defined for local filesystems are divided into two parts. Common to all local filesystems are hierarchical naming, locking, quotas, attribute management, and protection. These features are independent of how the data will be stored. 4.4BSD has a single implementation to provide these semantics. The other part of the local filesystem is the organization and management of the data on the storage media. Laying out the contents of files on the storage media is the responsibility of the filestore. 4.4BSD supports three different filestore layouts: * The traditional Berkeley Fast Filesystem * The log-structured filesystem, based on the Sprite operating-system design <> * A memory-based filesystem Although the organizations of these filestores are completely different, these differences are indistinguishable to the processes using the filestores. The Fast Filesystem organizes data into cylinder groups. Files that are likely to be accessed together, based on their locations in the filesystem hierarchy, are stored in the same cylinder group. Files that are not expected to accessed together are moved into different cylinder groups. Thus, files written at the same time may be placed far apart on the disk. The log-structured filesystem organizes data as a log. All data being written at any point in time are gathered together, and are written at the same disk location. Data are never overwritten; instead, a new copy of the file is written that replaces the old one. The old files are reclaimed by a garbage-collection process that runs when the filesystem becomes full and additional free space is needed. The memory-based filesystem is designed to store data in virtual memory. It is used for filesystems that need to support fast but temporary data, such as `/tmp`. The goal of the memory-based filesystem is to keep the storage packed as compactly as possible to minimize the usage of virtual-memory resources. [[overview-nfs]] === Network Filesystem Initially, networking was used to transfer data from one machine to another. Later, it evolved to allowing users to log in remotely to another machine. The next logical step was to bring the data to the user, instead of having the user go to the data -- and network filesystems were born. Users working locally do not experience the network delays on each keystroke, so they have a more responsive environment. Bringing the filesystem to a local machine was among the first of the major client-server applications. The _server_ is the remote machine that exports one or more of its filesystems. The _client_ is the local machine that imports those filesystems. From the local client's point of view, a remotely mounted filesystem appears in the file-tree name space just like any other locally mounted filesystem. Local clients can change into directories on the remote filesystem, and can read, write, and execute binaries within that remote filesystem identically to the way that they can do these operations on a local filesystem. When the local client does an operation on a remote filesystem, the request is packaged and is sent to the server. The server does the requested operation and returns either the requested information or an error indicating why the request was denied. To get reasonable performance, the client must cache frequently accessed data. The complexity of remote filesystems lies in maintaining cache consistency between the server and its many clients. Although many remote-filesystem protocols have been developed over the years, the most pervasive one in use among UNIX systems is the Network Filesystem (NFS), whose protocol and most widely used implementation were done by Sun Microsystems. The 4.4BSD kernel supports the NFS protocol, although the implementation was done independently from the protocol specification <>. The NFS protocol is described in Chapter 9. [[overview-terminal]] === Terminals Terminals support the standard system I/O operations, as well as a collection of terminal-specific operations to control input-character editing and output delays. At the lowest level are the terminal device drivers that control the hardware terminal ports. Terminal input is handled according to the underlying communication characteristics, such as baud rate, and according to a set of software-controllable parameters, such as parity checking. Layered above the terminal device drivers are line disciplines that provide various degrees of character processing. The default line discipline is selected when a port is being used for an interactive login. The line discipline is run in _canonical mode_; input is processed to provide standard line-oriented editing functions, and input is presented to a process on a line-by-line basis. Screen editors and programs that communicate with other computers generally run in _noncanonical mode_ (also commonly referred to as _raw mode_ or _character-at-a-time mode_). In this mode, input is passed through to the reading process immediately and without interpretation. All special-character input processing is disabled, no erase or other line editing processing is done, and all characters are passed to the program that is reading from the terminal. It is possible to configure the terminal in thousands of combinations between these two extremes. For example, a screen editor that wanted to receive user interrupts asynchronously might enable the special characters that generate signals and enable output flow control, but otherwise run in noncanonical mode; all other characters would be passed through to the process uninterpreted. On output, the terminal handler provides simple formatting services, including * Converting the line-feed character to the two-character carriage-return-line-feed sequence * Inserting delays after certain standard control characters * Expanding tabs * Displaying echoed nongraphic ASCII characters as a two-character sequence of the form `^C` (i.e., the ASCII caret character followed by the ASCII character that is the character's value offset from the ASCII `@` character). Each of these formatting services can be disabled individually by a process through control requests. [[overview-ipc]] === Interprocess Communication Interprocess communication in 4.4BSD is organized in _communication domains_. Domains currently supported include the _local domain_, for communication between processes executing on the same machine; the _internet domain_, for communication between processes using the TCP/IP protocol suite (perhaps within the Internet); the ISO/OSI protocol family for communication between sites required to run them; and the _XNS domain_, for communication between processes using the XEROX Network Systems (XNS) protocols. Within a domain, communication takes place between communication endpoints known as _sockets_. As mentioned in Section 2.6, the _socket_ system call creates a socket and returns a descriptor; other IPC system calls are described in Chapter 11. Each socket has a type that defines its communications semantics; these semantics include properties such as reliability, ordering, and prevention of duplication of messages. Each socket has associated with it a _communication protocol_. This protocol provides the semantics required by the socket according to the latter's type. Applications may request a specific protocol when creating a socket, or may allow the system to select a protocol that is appropriate for the type of socket being created. Sockets may have addresses bound to them. The form and meaning of socket addresses are dependent on the communication domain in which the socket is created. Binding a name to a socket in the local domain causes a file to be created in the filesystem. Normal data transmitted and received through sockets are untyped. Data-representation issues are the responsibility of libraries built on top of the interprocess-communication facilities. In addition to transporting normal data, communication domains may support the transmission and reception of specially typed data, termed _access rights_. The local domain, for example, uses this facility to pass descriptors between processes. Networking implementations on UNIX before 4.2BSD usually worked by overloading the character-device interfaces. One goal of the socket interface was for naive programs to be able to work without change on stream-style connections. Such programs can work only if the _read_ and _write_ systems calls are unchanged. Consequently, the original interfaces were left intact, and were made to work on stream-type sockets. A new interface was added for more complicated sockets, such as those used to send datagrams, with which a destination address must be presented with each _send_ call. Another benefit is that the new interface is highly portable. Shortly after a test release was available from Berkeley, the socket interface had been ported to System III by a UNIX vendor (although AT&T did not support the socket interface until the release of System V Release 4, deciding instead to use the Eighth Edition stream mechanism). The socket interface was also ported to run in many Ethernet boards by vendors, such as Excelan and Interlan, that were selling into the PC market, where the machines were too small to run networking in the main processor. More recently, the socket interface was used as the basis for Microsoft's Winsock networking interface for Windows. [[overview-network-communication]] === Network Communication Some of the communication domains supported by the _socket_ IPC mechanism provide access to network protocols. These protocols are implemented as a separate software layer logically below the socket software in the kernel. The kernel provides many ancillary services, such as buffer management, message routing, standardized interfaces to the protocols, and interfaces to the network interface drivers for the use of the various network protocols. At the time that 4.2BSD was being implemented, there were many networking protocols in use or under development, each with its own strengths and weaknesses. There was no clearly superior protocol or protocol suite. By supporting multiple protocols, 4.2BSD could provide interoperability and resource sharing among the diverse set of machines that was available in the Berkeley environment. Multiple-protocol support also provides for future changes. Today's protocols designed for 10- to 100-Mbit-per-second Ethernets are likely to be inadequate for tomorrow's 1- to 10-Gbit-per-second fiber-optic networks. Consequently, the network-communication layer is designed to support multiple protocols. New protocols are added to the kernel without the support for older protocols being affected. Older applications can continue to operate using the old protocol over the same physical network as is used by newer applications running with a newer network protocol. [[overview-network-implementation]] === Network Implementation The first protocol suite implemented in 4.2BSD was DARPA's Transmission Control Protocol/Internet Protocol (TCP/IP). The CSRG chose TCP/IP as the first network to incorporate into the socket IPC framework, because a 4.1BSD-based implementation was publicly available from a DARPA-sponsored project at Bolt, Beranek, and Newman (BBN). That was an influential choice: The 4.2BSD implementation is the main reason for the extremely widespread use of this protocol suite. Later performance and capability improvements to the TCP/IP implementation have also been widely adopted. The TCP/IP implementation is described in detail in Chapter 13. The release of 4.3BSD added the Xerox Network Systems (XNS) protocol suite, partly building on work done at the University of Maryland and at Cornell University. This suite was needed to connect isolated machines that could not communicate using TCP/IP. The release of 4.4BSD added the ISO protocol suite because of the latter's increasing visibility both within and outside the United States. Because of the somewhat different semantics defined for the ISO protocols, some minor changes were required in the socket interface to accommodate these semantics. The changes were made such that they were invisible to clients of other existing protocols. The ISO protocols also required extensive addition to the two-level routing tables provided by the kernel in 4.3BSD. The greatly expanded routing capabilities of 4.4BSD include arbitrary levels of routing with variable-length addresses and network masks. [[overview-operation]] === System Operation Bootstrapping mechanisms are used to start the system running. First, the 4.4BSD kernel must be loaded into the main memory of the processor. Once loaded, it must go through an initialization phase to set the hardware into a known state. Next, the kernel must do autoconfiguration, a process that finds and configures the peripherals that are attached to the processor. The system begins running in single-user mode while a start-up script does disk checks and starts the accounting and quota checking. Finally, the start-up script starts the general system services and brings up the system to full multiuser operation. During multiuser operation, processes wait for login requests on the terminal lines and network ports that have been configured for user access. When a login request is detected, a login process is spawned and user validation is done. When the login validation is successful, a login shell is created from which the user can run additional processes. :sectnums!: [bibliography] [[references]] == References [[biblio-accetta]] Accetta et al, 1986 Mach: A New Kernel Foundation for UNIX Development" M.Accetta R.Baron W.Bolosky D.Golub R.Rashid A.Tevanian M.Young 93-113 USENIX Association Conference Proceedings USENIX Association June 1986 [[biblio-cheriton]] Cheriton, 1988 The V Distributed System D. R.Cheriton 314-333 Comm ACM, 31, 3 March 1988 [[biblio-ewens]] Ewens et al, 1985 Tunis: A Distributed Multiprocessor Operating System P.Ewens D. R.Blythe M.Funkenhauser R. C.Holt 247-254 USENIX Assocation Conference Proceedings USENIX Association June 1985 [[biblio-gingell]] Gingell et al, 1987 Virtual Memory Architecture in SunOS R.Gingell J.Moran W.Shannon 81-94 USENIX Association Conference Proceedings USENIX Association June 1987 [[biblio-kernighan]] Kernighan & Pike, 1984 The UNIX Programming Environment B. W.Kernighan R.Pike Prentice-Hall Englewood Cliffs NJ 1984 [[biblio-macklem]] Macklem, 1994 The 4.4BSD NFS Implementation R.Macklem 6:1-14 4.4BSD System Manager's Manual O'Reilly & Associates, Inc. Sebastopol CA 1994 [[biblio-mckusick-2]] McKusick & Karels, 1988 Design of a General Purpose Memory Allocator for the 4.3BSD UNIX Kernel M. K.McKusick M. J.Karels 295-304 USENIX Assocation Conference Proceedings USENIX Assocation June 1998 [[biblio-mckusick-1]] McKusick et al, 1994 Berkeley Software Architecture Manual, 4.4BSD Edition M. K.McKusick M. J.Karels S. J.Leffler W. N.Joy R. S.Faber 5:1-42 4.4BSD Programmer's Supplementary Documents O'Reilly & Associates, Inc. Sebastopol CA 1994 [[biblio-ritchie]] Ritchie, 1988 Early Kernel Design private communication D. M.Ritchie March 1988 [[biblio-rosenblum]] Rosenblum & Ousterhout, 1992 The Design and Implementation of a Log-Structured File System M.Rosenblum K.Ousterhout 26-52 ACM Transactions on Computer Systems, 10, 1 Association for Computing Machinery February 1992 [[biblio-rozier]] Rozier et al, 1988 Chorus Distributed Operating Systems M.Rozier V.Abrossimov F.Armand I.Boule M.Gien M.Guillemont F.Herrmann C.Kaiser S.Langlois P.Leonard W.Neuhauser 305-370 USENIX Computing Systems, 1, 4 Fall 1988 [[biblio-tevanian]] Tevanian, 1987 Architecture-Independent Virtual Memory Management for Parallel and Distributed Environments: The Mach Approach Technical Report CMU-CS-88-106, A.Tevanian Department of Computer Science, Carnegie-Mellon University Pittsburgh PA December 1987 diff --git a/documentation/content/en/books/dev-model/_index.adoc b/documentation/content/en/books/dev-model/_index.adoc index 374e9b484a..a8314d44f5 100644 --- a/documentation/content/en/books/dev-model/_index.adoc +++ b/documentation/content/en/books/dev-model/_index.adoc @@ -1,1284 +1,1284 @@ --- title: A project model for the FreeBSD Project authors: - author: Niklas Saers copyright: Copyright © 2002-2005 Niklas Saers description: A formal study of the organization of the FreeBSD project trademarks: ["freebsd", "ibm", "ieee", "adobe", "intel", "linux", "microsoft", "opengroup", "sun", "netbsd", "general"] bookOrder: 45 tags: ["model", "project model", "FreeBSD"] --- //// Copyright (c) 2002-2005 Niklas Saers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. //// = A project model for the FreeBSD Project :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/dev-model/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../images/{images-path} include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] ''' toc::[] [[foreword]] [.abstract-title] Foreword 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:[This goes hand-in-hand with Brooks' law that adding another person to a late project will make it later since it will increase the communication needs . A project model is a tool to reduce the communication needs.] 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 [<>]. 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. * Andrey A. Chernov mailto:ache@freebsd.org[ache@freebsd.org] * Bruce A. Mah mailto:bmah@freebsd.org[bmah@freebsd.org] * Dag-Erling Smørgrav mailto:des@freebsd.org[des@freebsd.org] * Giorgos Keramidas mailto:keramida@freebsd.org[keramida@freebsd.org] * Ingvil Hovig mailto:ingvil.hovig@skatteetaten.no[ingvil.hovig@skatteetaten.no] * Jesper Holck mailto:jeh.inf@cbs.dk[jeh.inf@cbs.dk] * John Baldwin mailto:jhb@freebsd.org[jhb@freebsd.org] * John Polstra mailto:jdp@freebsd.org[jdp@freebsd.org] * Kirk McKusick mailto:mckusick@freebsd.org[mckusick@freebsd.org] * Mark Linimon mailto:linimon@freebsd.org[linimon@freebsd.org] * Marleen Devos * Niels Jørgenssen mailto:nielsj@ruc.dk[nielsj@ruc.dk] * Nik Clayton mailto:nik@freebsd.org[nik@freebsd.org] * Poul-Henning Kamp mailto:phk@freebsd.org[phk@freebsd.org] * Simon L. Nielsen mailto:simon@freebsd.org[simon@freebsd.org] [[overview]] == Overview A project model is a means to reduce the communications overhead in a project. As shown by [<>], increasing the number of project participants increases the communication in the project exponentionally. FreeBSD has during the past few years increased both its mass of active users and committers, and the communication in the project has risen accordingly. This project model will serve to reduce this overhead by providing an up-to-date description of the project. During the Core elections in 2002, Mark Murray stated "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." [<>]. 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. The FreeBSD project model will be described as of July 1st, 2004. It is based on the Niels Jørgensen's paper [<>], FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers. 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. [<>] Section 1.2 and 1.3 give the vision and the architectural guidelines for the project. The vision is "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." The architectural guidelines help determine whether a problem that someone wants to be solved is within the scope of the project [[definitions]] == Definitions [[ref-activity]] === Activity An "activity" is an element of work performed during the course of a project [<>]. 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. [[def-process]] === Process A "process" 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. [[ref-hat]] === Hat A "hat" 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. [[ref-outcome]] === Outcome An "outcome" is the final output of the process. This is synonymous with deliverable, that is defined as "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" by [<>]. Examples of outcomes are a piece of software, a decision made or a report written. [[ref-freebsd]] === FreeBSD When saying "FreeBSD" we will mean the BSD derivative UNIX-like operating system FreeBSD, whereas when saying "the FreeBSD Project" we will mean the project organisation. [[model-orgstruct]] == Organisational structure 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. The FreeBSD Project's structure (in order of descending authority) [.informaltable] [cols="1,1", options="header"] |=== | Group | Number of people |Core members |9 |Committers |269 |Contributors |~3000 |=== Number of committers has been determined by going through CVS logs from January 1st, 2004 to December 31st, 2004 and contributors by going through the list of contributions and problem reports. 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 of January 1st, 2003, there are an estimated 5500 contributors on the project. 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. The project can be grouped into four distinct separate parts, and most developers will focus their involvement in one part of FreeBSD. The four parts are kernel development, userland development, ports and documentation. When referring to the base system, both kernel and userland is meant. This split changes our table to look like this: The FreeBSD Project's structure with committers in categories [.informaltable] [cols="1,1,1", options="header"] |=== | Group | Category | Number of people |Core members | |9 |Committers |Kernel |56 | |Userland |50 | |Docs |9 | |Ports |120 | |Total |269 |Contributors | |~3000 |=== Number of committers per area has been determined by going through CVS logs from January 1st, 2004 to December 31st, 2004. Note that many committers work in multiple areas, making the total number higher than the real number of committers. The total number of committers at that time was 269. 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 table is higher than in the above table. 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 require a closer coordination than userland applications do. The core utilities, known as userland, provide the interface that identifies FreeBSD, both user interface, shared libraries and external interfaces to connecting clients. Currently, 162 people are involved in userland development and maintenance, many being maintainers for their own part of the code. Maintainership will be discussed in the <> section. Documentation is handled by <> and includes all documents surrounding the FreeBSD project, including the web pages. There were during 2004 101 people making commits to the FreeBSD Documentation Project. Ports is the collection of meta-data that is needed to make software packages build correctly on FreeBSD. An example of a port is the port for the web-browser Mozilla. It contains information about where to fetch the source, what patches to apply and how, and how the package should be installed on the system. This allows automated tools to fetch, build and install the package. As of this writing, there are more than 12600 ports available. footnote:[Statistics are generated by counting the number of entries in the file fetched by portsdb by April 1st, 2005. portsdb is a part of the port sysutils/portupgrade.] , 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 <>. [[methodology-model]] == Methodology model [[development-model]] === Development model 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. Jørgenssen's model for change integration [.informaltable] [cols="1,1,1", options="header"] |=== | Stage | Next if successful | Next if unsuccessful |code |review | |review |pre-commit test |code |pre-commit test |development release |code |development release |parallel debugging |code |parallel debugging |production release |code |production release | |code |=== The "development release" is the FreeBSD-CURRENT ("-CURRENT") branch and the "production release" is the FreeBSD-STABLE branch ("-STABLE") [<>]. 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. 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 they are waiting for review or people to test one or more of their changes, they may be writing another change. As each commit represents an increment, this is a massively incremental model. The commits are in fact so frequent that during one year footnote:[The period from January 1st, 2004 to December 31st, 2004 was examined to find this number.] , 85427 commits were made, making a daily average of 233 commits. Within the "code" bracket in Jørgensen's model, each programmer has their own working style and follows their own development models. The bracket could very well have been called "development" 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. 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). It is important to notice the word "change". Most commits do not contain radical new features, but are maintenance updates. 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. 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:[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.]. 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. 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:[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.] As design is a part of the "Code" 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. [[release-branches]] === Release branches The releases of FreeBSD are 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. In the following release tree, arrows that follow one-another in a particular direction represent a branch. Boxes with full lines and diamonds represent official releases. Boxes with dotted lines represent the development branch at that time. Security branches are represented by ovals. Diamonds differ from boxes in that they represent a fork, meaning a place where a branch splits into two branches where one of the branches becomes a sub-branch. For example, at 4.0-RELEASE the 4.0-CURRENT branch split into 4-STABLE and 5.0-CURRENT. At 4.5-RELEASE, the branch forked off a security branch called RELENG_4_5. .The FreeBSD release tree image::branches.png[Refer to table below for a screen-reader friendly version.] [.informaltable] [cols="1,1,1", options="header"] |=== | Major release | Forked from | Following minor releases |... | | |3.0 Current (development branch) | |Releng 3 branches: 3.0 Release to 3.5 Release, leading to 3.5.1 Release and the subsequent 3 Stable branch |4.0 Current (development branch) |3.1 Release |Releng 4 branches: 4.1 Release to 4.6 Release (and 4.6.2 Release), then 4.7 Release to 4.11 Release (all starting at 4.3 Release also leading to a Releng_4_n branch), and the subsequent 4 Release branch |5.0 Current (development branch) |4.0 Release |Releng 5 branches: 5.0 Release to 5.4 Release (all except 5.0 and 5.3 also leading to a Releng_5_n branch), and the subsequent 5 Release branch |6.0 Current (development branch) |5.3 Release | |... | | |=== 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. [<>] A "major release" is always made from the -CURRENT branch. However, the -CURRENT branch does not need to fork at that point in time, but can focus on stabilising. An example of this is that following 3.0-RELEASE, 3.1-RELEASE was also a continuation of the -CURRENT-branch, and -CURRENT did not become a true development branch until this version was released and the 3-STABLE branch was forked. When -CURRENT returns to becoming a development branch, it can only be followed by a major release. 5-STABLE is predicted to be forked off 5.0-CURRENT at around 5.3-RELEASE. It is not until 5-STABLE is forked that the development branch will be branded 6.0-CURRENT. A "minor release" is made from the -CURRENT branch following a major release, or from the -STABLE branch. Following and including, 4.3-RELEASEfootnote:[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.], when a minor release has been made, it becomes a "security branch". 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:[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.] Each update to a security branch is called a "patchlevel". 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. [[model-summary]] === Model summary To summarise, the development model of FreeBSD can be seen as the following tree: .The overall development model image::freebsd-code-model.png[Refer to paragraphs below for a screen-reader friendly version.] The tree of the FreeBSD development with ongoing development efforts and continuous integration. 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. Below the -STABLE branch are old, unsupported versions. 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. Many committers have a special area of responsibility. These roles are called hats. These hats can be either project roles, such as public relations officer, or maintainer for a certain area of the code. Because this is a project where people give voluntarily of their spare time, people with assigned hats are not always available. They must therefore appoint a deputy that can perform the hat's role in their absence. The other option is to have the role held by a group. 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. [[sect-hats]] == Hats [[general-hats]] === General Hats [[role-contributor]] ==== Contributor 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. [<>] [[role-committer]] ==== Committer A person who has the required privileges to add their code or documentation to the repository. A committer has made a commit within the past 12 months. [<>] An active committer is a committer who has made an average of one commit per month during that time. It is worth noting that there are no technical barriers to prevent someone, once having gained commit privileges to the main- or a sub-project, to make commits in parts of that project's source the committer did not specifically get permission to modify. However, when wanting to make modifications to parts a committer has not been involved in before, they should read the logs to see what has happened in this area before, and also read the MAINTAINERS file to see if the maintainer of this part has any special requests on how changes in the code should be made. [[role-core]] ==== Core Team 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 of July 1st, 2004, core consisted of 9 members. Elections are held every two years. [[role-maintainer]] ==== Maintainership -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. +Maintainership means that the person is responsible for what is allowed to go into that area of the code and has the final say should disagreements over the code occur. This involves proactive work aimed at stimulating contributions and reactive work in reviewing commits. 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. 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. Maintainership of a particular piece of code is a hat that is not held as a group. [[official-hats]] === Official Hats 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 list shows the responsibility lines and gives a description of each hat, including who it is held by. [[role-doc-manager]] ==== Documentation project manager <> architect is responsible for defining and following up documentation goals for the committers in the Documentation project, which they supervise. Hat held by: The DocEng team mailto:doceng@FreeBSD.org[doceng@FreeBSD.org]. The https://www.freebsd.org/internal/doceng/[ DocEng Charter]. [[role-postmaster]] ==== Postmaster The Postmaster is responsible for mail being correctly delivered to the committers' email address. They are 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. Hat currently held by: the Postmaster Team mailto:postmaster@FreeBSD.org[postmaster@FreeBSD.org]. [[role-release-coordination]] ==== Release Coordination The responsibilities of the Release Engineering Team are * Setting, publishing and following a release schedule for official releases * Documenting and formalising release engineering procedures * Creation and maintenance of code branches * Coordinating with the Ports and Documentation teams to have an updated set of packages and documentation released with the new releases * Coordinating with the Security team so that pending releases are not affected by recently disclosed vulnerabilities. Further information about the development process is available in the <> section. [[role-releng]] Hat held by: the Release Engineering team mailto:re@FreeBSD.org[re@FreeBSD.org]. The https://www.freebsd.org/releng/charter/[ Release Engineering Charter]. [[role-pr-cr]] ==== Public Relations & Corporate Liaison The Public Relations & Corporate Liaison's responsibilities are: * Making press statements when happenings that are important to the FreeBSD Project happen. * Being the official contact person for corporations that are working close with the FreeBSD Project. * Take steps to promote FreeBSD within both the Open Source community and the corporate world. * Handle the "freebsd-advocacy" mailing list. This hat is currently not occupied. [[role-security-officer]] ==== Security Officer 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 behavior when it comes to security. 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 <> members, receive sensitive information about security issues. However, to create or implement a patch, the Security Officer has the Security Officer Team mailto:security-team@FreeBSD.org[security-team@FreeBSD.org] to help do the work. [[role-repo-manager]] ==== Source Repository Manager The Source Repository Manager is the only one who is allowed to directly modify the repository without using the <> tool. It is their 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 SVN technical problem. Hat held by: the Source Repository Manager mailto:clusteradm@FreeBSD.org[clusteradm@FreeBSD.org]. [[role-election-manager]] ==== Election Manager The Election Manager is responsible for the <> process. The manager is responsible for running and maintaining the election system, and is the final authority should minor unforeseen events happen in the election process. Major unforeseen events have to be discussed with the <> Hat held only during elections. [[role-webmaster]] ==== Web site Management 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 <> and acts as maintainer for the "www" tree. Hat held by: the FreeBSD Webmasters mailto:www@FreeBSD.org[www@FreeBSD.org]. [[role-ports-manager]] ==== Ports Manager The Ports Manager acts as a liaison between <> and the core project, and all requests from the project should go to the ports manager. Hat held by: the Ports Management Team mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org]. The https://www.freebsd.org/portmgr/charter/[Portmgr charter]. [[role-standards]] ==== Standards The Standards hat is responsible for ensuring that FreeBSD complies with the standards it is committed to , 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. Hat currently held by: Garrett Wollman mailto:wollman@FreeBSD.org[wollman@FreeBSD.org]. [[role-core-secretary]] ==== Core Secretary 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. Hat currently held by: {bofh}. [[role-bugmeister]] ==== Bugmeister The Bugmeister 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. They supervise bugbusters. Hat currently held by: the Bugmeister Team mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org]. [[role-donations]] ==== Donations Liaison Officer The task of the donations liaison officer is to match the developers with needs with people or organisations willing to make a donation. Hat held by: the Donations Liaison Office mailto:donations@FreeBSD.org[donations@FreeBSD.org]. The https://www.freebsd.org/donations/[ Donations Liaison Charter]. [[role-admin]] ==== Admin (Also called "FreeBSD Cluster Admin") The admin team consists of the people responsible for administrating the computers that the project relies on for its distributed work and communication to be synchronised. It consists mainly of those people who have physical access to the servers. Hat held by: the Admin team mailto:admin@FreeBSD.org[admin@FreeBSD.org]. [[proc-depend-hats]] === Process dependent hats [[role-problem-originator]] ==== Report originator The person originally responsible for filing a Problem Report. [[role-bugbuster]] ==== Bugbuster 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. [[role-mentor]] ==== Mentor A mentor is a committer who takes it upon them to introduce a new committer to the project, both in terms of ensuring the new committer's setup is valid, that the new committer knows the available tools required in their work, and that the new committer knows what is expected of them in terms of behavior. [[role-vendor]] ==== Vendor The person(s) or organisation whom external code comes from and whom patches are sent to. [[role-reviewer]] ==== Reviewers People on the mailing list where the request for review is posted. 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. [[model-processes]] == Processes [[proc-addrem-committer]] === Adding new and removing old committers 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. 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. 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. When a contributor is given committer status, they are assigned a mentor. The committer who recommended the new committer will, in the general case, take it upon themselves to be the new committers mentor. When a contributor is given their commit bit, a <>-signed email is sent from either <>, <>, 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, <> public key, and PGP key from the new committer and sends them to <>. When the new account is created, the mentor activates the commit bit and guides the new committer through the rest of the initial process. .Process summary: adding a new committer image::proc-add-committer.png[Refer to paragraph below for a screen-reader friendly version.] When a contributor sends a piece of code, the receiving committer may choose to recommend that the contributor is given commit privileges. If they recommend this to core, core will vote on this recommendation. If the vote is in favour, a mentor is assigned the new committer and the new committer has to email their details to the administrators for an account to be created. After this, the new committer is all set to make their first commit. By tradition, this is by adding their name to the committers list. 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. [<>] There are, however, no automatic procedures for doing this. For reactions concerning commit privileges not triggered by time, see <>. .Process summary: removing a committer image::proc-rm-committer.png[Refer to paragraph below for a screen-reader friendly version.] 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 and their account removed by the administrators. 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. Roles in this process: . <> . <> . <> . <> . <> [<>] [<>] [<>] [[committing]] === Committing code 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 "committer". Committers commit either code written by themselves, code submitted to them, or code submitted through a <>. When code is written by the developer that is non-trivial, they 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, they should ensure it compiles correctly with the entire tree and that all relevant tests run. This is called "pre-commit test". When contributed code is received, it should be reviewed by the committer and tested the same way. When a change is committed to a part of the source that has been contributed from an outside <>, 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. After the code has been available for review and no further changes are necessary, the code is committed into the development branch, -CURRENT. If the change applies for the -STABLE branch or the other branches as well, a "Merge From Current" ("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 them to commit it to the -STABLE branch (and possibly security branches as well). Only security critical changes should be merged to security branches. Delaying the commit to -STABLE and other branches allows for "parallel debugging" 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. .Process summary: A committer commits code image::proc-commit.png[Refer to paragraph below for a screen-reader friendly version.] When a committer has written a piece of code and wants to commit it, they first need 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, they 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 then 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, they can choose to implement or ignore the patch. .Process summary: A contributor commits code image::proc-contrib.png[Refer to paragraphs below and above for a screen-reader friendly version.] The difference when a contributor makes a code contribution is that they submit the code through the Bugzilla interface. This report is picked up by the maintainer who reviews the code and commits it. Hats included in this process are: . <> . <> . <> . <> [<>] [<>] [[process-core-election]] === Core election Core elections are held at least every two years. footnote:[The first Core election was held September 2000] 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. 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. 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 http://election.uk.freebsd.org/candidates.html[candidates list]. When writing their election statements, the candidates must answer a few standard questions submitted by the election manager. 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. 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 "developers" mailing list that is available to all committers. 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. Should there be a voting tie, this will be resolved by the new, unambiguously elected core members. Votes and candidate statements are archived, but the archives are not publicly available. .Process summary: Core elections image::proc-elections.png[Refer to paragraph below for a screen-reader friendly version.] Core announces the election and selects an election manager who 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. Hats in core elections are: * <> * <> * <> [<>] [<>] [<>] [[new-features]] === Development of new features Within the project there are sub-projects that are working on new features. These projects are generally done by one person [<>]. 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. 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 their time between the request and their 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 <> tool. 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. 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 prioritisation 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. 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:[More and more tests are however performed when building the system (make world). These tests are however a very new addition and no systematic framework for these tests have yet been created.] [[model-maintenance]] === Maintenance 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:[sendmail and named are examples of code that has been merged from other platforms.] 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. The main bulk of work that is put into the FreeBSD project is maintenance. [<>] has made a figure showing the life cycle of changes. Jørgenssen's model for change integration [.informaltable] [cols="1,1,1", options="header"] |=== | Stage | Next if successful | Next if unsuccessful |code |review | |review |pre-commit test |code |pre-commit test |development release |code |development release |parallel debugging |code |parallel debugging |production release |code |production release | |code |=== Here "development release" refers to the -CURRENT branch while "production release" refers to the -STABLE branch. The "pre-commit test" 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. "Parallel debugging" is the functional testing that can trigger more review, and debugging when the code is included in the -CURRENT branch. As of this writing, there were 269 committers in the project. When they commit a change to a branch, that constitutes a new release. It is very common for users in the community to track a particular branch. The immediate existence of a new release makes the changes widely available right away and allows for rapid feedback from the community. This also gives the community the response time they expect on issues that are of importance to them. This makes the community more engaged, and thus allows for more and better feedback that again spurs more maintenance and ultimately should create a better product. 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. [[model-pr]] === Problem reporting Before FreeBSD 10, FreeBSD included a problem reporting tool called `send-pr`. Problems include bug reports, feature requests, feature enhancements and notices of new versions of external software that are included in the project. Although `send-pr` is available, users and developers are encouraged to submit issues using our https://bugs.freebsd.org/submit/[ problem report form]. Problem reports are sent to an email address where it is inserted into the Problem Reports maintenance database. A <> 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 <>. 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. .Process summary: problem reporting image::proc-pr.png[Refer to paragraph below for a screen-reader friendly version.] A problem is reported by the report originator. It is then classified by a bugbuster and handed to the correct maintainer. They verify the problem and discuss the problem with the originator until they have enough information to create a working patch. This patch is then committed and the problem report is closed. The roles included in this process are: . <> . <> . <> [<>]. [<>] [[process-reactions]] === Reacting to misbehavior [<>] 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 misbehavior. They specify what actions will result in how long a suspension of the committer's commit privileges. * Committing during code freezes without the approval of the Release Engineering team - 2 days * Committing to a security branch without approval - 2 days * Commit wars - 5 days to all participating parties * Impolite or inappropriate behavior - 5 days [<>] For the suspensions to be efficient, any single core member can implement a suspension before discussing it on the "core" 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 "developers" mailing list, a list available to committers only. It is important that you cannot be suspended for making technical errors. All penalties come from breaking social etiquette. Hats involved in this process: * <> * <> [[process-release-engineering]] === Release engineering The FreeBSD project has a Release Engineering 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 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. 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 they find that the changes are not suitable to be included in the release. There are three different kinds of releases: . .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 . .X releases are releases of the -STABLE branch. They are scheduled to come out every 4 months. . .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. 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 CD-ROM images. However, the release is not considered "really released" until a <>-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:[Many commercial vendors use these images to create CD-ROMs that are sold in retail outlets.]. The releases of the -CURRENT-branch (that is, all releases that end with ".0") 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. *.0 releases go into their own branch and are aimed mainly at early adopters. The branch then goes through a period of stabilisation, and it is not until the <> decides the demands to stability have been satisfied that the branch becomes -STABLE and -CURRENT targets the next major version. While this for the majority has been with *.1 versions, this is not a demand. Most releases are made when a given date that has been deemed a long enough time since the previous release comes. A target is set for having major releases every 18 months and minor releases every 4 months. The user community has made it very clear that security and stability cannot be sacrificed by self-imposed deadlines and target release dates. For slips of time not to become too long with regards to security and stability issues, extra discipline is required when committing changes to -STABLE. . Make release schedule . Feature freeze . Code freeze . Make branch . Release candidate . Stabilize release (loop back to previous step as many times as necessary; when release is considered stable, proceed with next step) . Build packages . Warn mirrors . Publish release [<>] [[tools]] == Tools The major support tools for supporting the development process are Bugzilla, Mailman, and OpenSSH. These are externally developed tools and are commonly used in the open source world. [[tool-svn]] === Subversion (SVN) Subversion ("SVN") is a system to handle multiple versions of text files and tracking who committed what changes and why. A project lives within a "repository" and different versions are considered different "branches". [[tool-bugzilla]] === Bugzilla Bugzilla 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 its web interface to send "Problem Reports" to the project's central Bugzilla server. The committers also have web and command-line clients. [[model-mailman]] === Mailman Mailman is a program that automates the management of mailing lists. The FreeBSD Project uses it to run 16 general lists, 60 technical lists, 4 limited lists and 5 lists with SVN commit logs. It is also used for many mailing lists set up and used by other people and projects in the FreeBSD community. General lists are lists for the general public, technical lists are mainly for the development of specific areas of interest, and closed lists are for internal communication not intended for the general public. The majority of all the communication in the project goes through these 85 lists [<>, Appendix C]. [[tool-pgp]] === Pretty Good Privacy 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 to 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. [[tool-ssh2]] === Secure Shell 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. [[sub-projects]] == Sub-projects 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. [[sub-project-ports]] === The Ports Subproject A "port" 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 has grown at a tremendous rate, as shown by the following figure. .Number of ports added between 1996 and 2008 [[fig-ports]] image::portsstatus.png[Refer to tables below for a screen-reader friendly version.] <> shows the number of ports available to FreeBSD in the period 1995 to 2008. It looks like the curve has first grown exponentially, and then from the middle of 2001 to the middle of 2007 grown linearly at a rate of about 2000 ports/year, before its growth rate gets lower. Approximate dates each multiple of 1000 ports is reached [.informaltable] [cols="1,1", options="header"] |=== | Number of ports | Approximate date |1000 |Late 1997 |2000 |Late 1998 |3000 |Early 2000 |4000 |Late 2000 |5000 |Mid 2001 |6000 |4th quarter of 2001 |7000 |Mid 2002 |8000 |4th quarter of 2002 |9000 |Mid 2003 |10000 |End of 2003 |11000 |Mid 2004 |12000 |End of 2004 |13000 |Mid 2005 |14000 |Early 2006 |15000 |Mid 2006 |16000 |3rd quarter 2006 |17000 |2nd quarter 2007 |=== Approximate number of ports at the start of each year [.informaltable] [cols="1,1", options="header"] |=== | Year | Approximate number of ports |1995 |100 |1996 |300 |1997 |700 |1998 |1200 |1999 |2000 |2000 |2900 |2001 |4300 |2002 |6200 |2003 |8100 |2004 |10050 |2005 |12100 |2006 |14000 |2007 |16200 |2008 |17900 |=== 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. Ports has its own core team with the <> 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. 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. 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. For efficiency of communication, teams depending on Ports, such as the release engineering team, have their own ports liaisons. [[sub-project-documentation]] === The FreeBSD Documentation Project 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. 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. The main tasks in the Documentation project are to work on current projects in the "FreeBSD Documentation Set", and translate the documentation to other languages. 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. Like the ports sub-project, the Documentation project can appoint documentation committers without FreeBSD Core's approval. [<>]. The Documentation project has extref:{fdp-primer}[a primer]. This is used both to introduce new project members to the standard tools and syntaxes and to act as a reference when working on the project. :sectnums!: [bibliography] [[bibliography]] == References [[brooks]] [Brooks, 1995] Frederick P. Brooks. Copyright © 1975, 1995 Pearson Education Limited. 0201835959. Addison-Wesley Pub Co. The Mythical Man-Month. Essays on Software Engineering, Anniversary Edition (2nd Edition). [[thesis]] [Saers, 2003] Niklas Saers. Copyright © 2003. A project model for the FreeBSD Project. Candidatus Scientiarum thesis. http://niklas.saers.com/thesis. [[jorgensen2001]] [Jørgensen, 2001] Niels Jørgensen. Copyright © 2001. Putting it All in the Trunk. Incremental Software Development in the FreeBSD Open Source Project. http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf. [[ref-pmbok]] [PMI, 2000] Project Management Institute. Copyright © 1996, 2000 Project Management Institute. 1-880410-23-0. Project Management Institute. Newtown Square Pennsylvania USA . PMBOK Guide. A Guide to the Project Management Body of Knowledge, 2000 Edition. [[freebsd-bylaws]] [FreeBSD, 2000A] Copyright © 2002 The FreeBSD Project. Core Bylaws. https://www.freebsd.org/internal/bylaws/. [[freebsd-developer-handbook]] [FreeBSD, 2002A] Copyright © 2002 The FreeBSD Documentation Project. FreeBSD Developer's Handbook. extref:{developers-handbook}[Developers Handbook]. [[bsd-election2002]] [FreeBSD, 2002B] Copyright © 2002 The FreeBSD Project. Core team election 2002. http://election.uk.freebsd.org/candidates.html. [[freebsd-handle-pr]] [FreeBSD, 2002C] Dag-Erling Smørgrav and Hiten Pandya. Copyright © 2002 The FreeBSD Documentation Project. The FreeBSD Documentation Project. Problem Report Handling Guidelines. extref:{pr-guidelines}[Problem Report Handling Guidelines]. [[freebsd-send-pr]] [FreeBSD, 2002D] Dag-Erling Smørgrav. Copyright © 2002 The FreeBSD Documentation Project. The FreeBSD Documentation Project. Writing FreeBSD Problem Reports. extref:{problem-reports}[Writing FreeBSD Problem Reports]. [[freebsd-committer]] [FreeBSD, 2001] Copyright © 2001 The FreeBSD Documentation Project. The FreeBSD Documentation Project. Committers Guide. extref:{committers-guide}[Committer's Guide]. [[freebsd-releng]] [FreeBSD, 2002E] Murray Stokely. Copyright © 2002 The FreeBSD Documentation Project. The FreeBSD Documentation Project. FreeBSD Release Engineering. extref:{releng}[FreeBSD Release Engineering]. [[ref-bsd-handbook]] [FreeBSD, 2003A] The FreeBSD Documentation Project. FreeBSD Handbook. extref:{handbook}[FreeBSD Handbook]. [[freebsd-contributors]] [FreeBSD, 2002F] Copyright © 2002 The FreeBSD Documentation Project. The FreeBSD Documentation Project. Contributors to FreeBSD. extref:{contributors}[Contributors to FreeBSD]. [[freebsd-election]] [FreeBSD, 2002G] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. Core team elections 2002. http://election.uk.freebsd.org. [[freebsd-expiration-policy]] [FreeBSD, 2002H] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. Commit Bit Expiration Policy. 2002/04/06 15:35:30. https://www.freebsd.org/internal/expire-bits/. [[freebsd-new-account]] [FreeBSD, 2002I] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. New Account Creation Procedure. 2002/08/19 17:11:27. https://www.freebsd.org/internal/new-account/. [[freebsd-doceng-charter]] [FreeBSD, 2003B] Copyright © 2002 The FreeBSD Documentation Project. The FreeBSD Documentation Project. FreeBSD DocEng Team Charter. 2003/03/16 12:17. https://www.freebsd.org/internal/doceng/. [[ref-freebsd-trenches]] [Lehey, 2002] Greg Lehey. Copyright © 2002 Greg Lehey. Greg Lehey. Two years in the trenches. The evolution of a software project. http://www.lemis.com/grog/In-the-trenches.pdf. diff --git a/documentation/content/en/books/dev-model/_index.po b/documentation/content/en/books/dev-model/_index.po index f8aceb77b9..44c34d7c87 100644 --- a/documentation/content/en/books/dev-model/_index.po +++ b/documentation/content/en/books/dev-model/_index.po @@ -1,3298 +1,3298 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2022-02-01 10:28-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/dev-model/_index.adoc:1 #, no-wrap msgid "A formal study of the organization of the FreeBSD project" msgstr "" #. Copyright (c) 2002-2005 Niklas Saers #. All rights reserved. #. Redistribution and use in source and binary forms, with or without #. modification, are permitted provided that the following conditions #. are met: #. 1. Redistributions of source code must retain the above copyright #. notice, this list of conditions and the following disclaimer. #. 2. Redistributions in binary form must reproduce the above copyright #. notice, this list of conditions and the following disclaimer in the #. documentation and/or other materials provided with the distribution. #. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND #. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE #. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE #. ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE #. FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL #. DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS #. OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) #. HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT #. LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY #. OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF #. SUCH DAMAGE. #. type: Title = #: documentation/content/en/books/dev-model/_index.adoc:1 #: documentation/content/en/books/dev-model/_index.adoc:38 #, no-wrap msgid "A project model for the FreeBSD Project" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:71 msgid "'''" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:77 msgid "Foreword" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:83 msgid "" "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:[This goes hand-in-hand with " "Brooks' law that adding another person to a late project will make it later " "since it will increase the communication needs . A project model is a tool " "to reduce the communication needs.] 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 [<>]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:85 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:87 msgid "Andrey A. Chernov mailto:ache@freebsd.org[ache@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:88 msgid "Bruce A. Mah mailto:bmah@freebsd.org[bmah@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:89 msgid "Dag-Erling Smørgrav mailto:des@freebsd.org[des@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:90 msgid "Giorgos Keramidas mailto:keramida@freebsd.org[keramida@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:91 msgid "" "Ingvil Hovig mailto:ingvil.hovig@skatteetaten.no[ingvil.hovig@skatteetaten." "no]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:92 msgid "Jesper Holck mailto:jeh.inf@cbs.dk[jeh.inf@cbs.dk]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:93 msgid "John Baldwin mailto:jhb@freebsd.org[jhb@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:94 msgid "John Polstra mailto:jdp@freebsd.org[jdp@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:95 msgid "Kirk McKusick mailto:mckusick@freebsd.org[mckusick@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:96 msgid "Mark Linimon mailto:linimon@freebsd.org[linimon@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:97 msgid "Marleen Devos" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:98 msgid "Niels Jørgenssen mailto:nielsj@ruc.dk[nielsj@ruc.dk]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:99 msgid "Nik Clayton mailto:nik@freebsd.org[nik@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:100 msgid "Poul-Henning Kamp mailto:phk@freebsd.org[phk@freebsd.org]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:101 msgid "Simon L. Nielsen mailto:simon@freebsd.org[simon@freebsd.org]" msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:103 #, no-wrap msgid "Overview" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:108 msgid "" "A project model is a means to reduce the communications overhead in a " "project. As shown by [<>], increasing the number of " "project participants increases the communication in the project " "exponentionally. FreeBSD has during the past few years increased both its " "mass of active users and committers, and the communication in the project " "has risen accordingly. This project model will serve to reduce this " "overhead by providing an up-to-date description of the project." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:114 msgid "" "During the Core elections in 2002, Mark Murray stated \"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.\" [<>]. 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:117 msgid "" "The FreeBSD project model will be described as of July 1st, 2004. It is " "based on the Niels Jørgensen's paper [<>], " "FreeBSD's official documents, discussions on FreeBSD mailing lists and " "interviews with developers." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:120 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:124 msgid "" "[<>] Section 1.2 and 1.3 give " "the vision and the architectural guidelines for the project. The vision is " "\"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.\" The architectural guidelines help determine " "whether a problem that someone wants to be solved is within the scope of the " "project" msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:126 #, no-wrap msgid "Definitions" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:129 #, no-wrap msgid "Activity" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:134 msgid "" "An \"activity\" is an element of work performed during the course of a " "project [<>]. 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:136 #, no-wrap msgid "Process" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:141 msgid "" "A \"process\" 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:143 #, no-wrap msgid "Hat" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:149 msgid "" "A \"hat\" 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:151 #, no-wrap msgid "Outcome" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:157 msgid "" "An \"outcome\" is the final output of the process. This is synonymous with " "deliverable, that is defined as \"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\" by [<>]. Examples of " "outcomes are a piece of software, a decision made or a report written." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:159 #, no-wrap msgid "FreeBSD" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:162 msgid "" "When saying \"FreeBSD\" we will mean the BSD derivative UNIX-like operating " "system FreeBSD, whereas when saying \"the FreeBSD Project\" we will mean the " "project organisation." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:164 #, no-wrap msgid "Organisational structure" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:167 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:169 msgid "The FreeBSD Project's structure (in order of descending authority)" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:174 #: documentation/content/en/books/dev-model/_index.adoc:209 #, no-wrap msgid "Group" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:176 #: documentation/content/en/books/dev-model/_index.adoc:212 #, no-wrap msgid "Number of people" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:177 #: documentation/content/en/books/dev-model/_index.adoc:213 #, no-wrap msgid "Core members" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:179 #: documentation/content/en/books/dev-model/_index.adoc:216 #: documentation/content/en/books/dev-model/_index.adoc:228 #, no-wrap msgid "9" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:180 #: documentation/content/en/books/dev-model/_index.adoc:217 #, no-wrap msgid "Committers" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:182 #: documentation/content/en/books/dev-model/_index.adoc:236 #, no-wrap msgid "269" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:183 #: documentation/content/en/books/dev-model/_index.adoc:237 #, no-wrap msgid "Contributors" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:184 #: documentation/content/en/books/dev-model/_index.adoc:239 #, no-wrap msgid "~3000" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:187 msgid "" "Number of committers has been determined by going through CVS logs from " "January 1st, 2004 to December 31st, 2004 and contributors by going through " "the list of contributions and problem reports." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:192 msgid "" "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 of January " "1st, 2003, there are an estimated 5500 contributors on the project." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:196 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:200 msgid "" "The project can be grouped into four distinct separate parts, and most " "developers will focus their involvement in one part of FreeBSD. The four " "parts are kernel development, userland development, ports and " "documentation. When referring to the base system, both kernel and userland " "is meant." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:202 msgid "This split changes our table to look like this:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:204 msgid "The FreeBSD Project's structure with committers in categories" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:210 #, no-wrap msgid "Category" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:218 #, no-wrap msgid "Kernel" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:220 #, no-wrap msgid "56" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:222 #, no-wrap msgid "Userland" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:224 #, no-wrap msgid "50" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:226 #, no-wrap msgid "Docs" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:230 #, no-wrap msgid "Ports" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:232 #, no-wrap msgid "120" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:234 #, no-wrap msgid "Total" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:244 msgid "" "Number of committers per area has been determined by going through CVS logs " "from January 1st, 2004 to December 31st, 2004. Note that many committers " "work in multiple areas, making the total number higher than the real number " "of committers. The total number of committers at that time was 269." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:247 msgid "" "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 table is " "higher than in the above table." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:252 msgid "" "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 require a closer coordination than userland applications do." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:256 msgid "" "The core utilities, known as userland, provide the interface that identifies " "FreeBSD, both user interface, shared libraries and external interfaces to " "connecting clients. Currently, 162 people are involved in userland " "development and maintenance, many being maintainers for their own part of " "the code. Maintainership will be discussed in the <> " "section." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:259 msgid "" "Documentation is handled by <> and includes all " "documents surrounding the FreeBSD project, including the web pages. There " "were during 2004 101 people making commits to the FreeBSD Documentation " "Project." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:267 msgid "" "Ports is the collection of meta-data that is needed to make software " "packages build correctly on FreeBSD. An example of a port is the port for " "the web-browser Mozilla. It contains information about where to fetch the " "source, what patches to apply and how, and how the package should be " "installed on the system. This allows automated tools to fetch, build and " "install the package. As of this writing, there are more than 12600 ports " "available. footnote:[Statistics are generated by counting the number of " "entries in the file fetched by portsdb by April 1st, 2005. portsdb is a part " "of the port sysutils/portupgrade.] , 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 <>." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:269 #, no-wrap msgid "Methodology model" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:272 #, no-wrap msgid "Development model" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:276 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:278 #: documentation/content/en/books/dev-model/_index.adoc:852 msgid "Jørgenssen's model for change integration" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:283 #: documentation/content/en/books/dev-model/_index.adoc:857 #, no-wrap msgid "Stage" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:284 #: documentation/content/en/books/dev-model/_index.adoc:858 #, no-wrap msgid "Next if successful" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:286 #: documentation/content/en/books/dev-model/_index.adoc:860 #, no-wrap msgid "Next if unsuccessful" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:287 #: documentation/content/en/books/dev-model/_index.adoc:294 #: documentation/content/en/books/dev-model/_index.adoc:298 #: documentation/content/en/books/dev-model/_index.adoc:302 #: documentation/content/en/books/dev-model/_index.adoc:306 #: documentation/content/en/books/dev-model/_index.adoc:309 #: documentation/content/en/books/dev-model/_index.adoc:861 #: documentation/content/en/books/dev-model/_index.adoc:868 #: documentation/content/en/books/dev-model/_index.adoc:872 #: documentation/content/en/books/dev-model/_index.adoc:876 #: documentation/content/en/books/dev-model/_index.adoc:880 #: documentation/content/en/books/dev-model/_index.adoc:883 #, no-wrap msgid "code" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:288 #: documentation/content/en/books/dev-model/_index.adoc:291 #: documentation/content/en/books/dev-model/_index.adoc:862 #: documentation/content/en/books/dev-model/_index.adoc:865 #, no-wrap msgid "review" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:292 #: documentation/content/en/books/dev-model/_index.adoc:295 #: documentation/content/en/books/dev-model/_index.adoc:866 #: documentation/content/en/books/dev-model/_index.adoc:869 #, no-wrap msgid "pre-commit test" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:296 #: documentation/content/en/books/dev-model/_index.adoc:299 #: documentation/content/en/books/dev-model/_index.adoc:870 #: documentation/content/en/books/dev-model/_index.adoc:873 #, no-wrap msgid "development release" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:300 #: documentation/content/en/books/dev-model/_index.adoc:303 #: documentation/content/en/books/dev-model/_index.adoc:874 #: documentation/content/en/books/dev-model/_index.adoc:877 #, no-wrap msgid "parallel debugging" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:304 #: documentation/content/en/books/dev-model/_index.adoc:307 #: documentation/content/en/books/dev-model/_index.adoc:878 #: documentation/content/en/books/dev-model/_index.adoc:881 #, no-wrap msgid "production release" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:312 msgid "" "The \"development release\" is the FreeBSD-CURRENT (\"-CURRENT\") branch and " "the \"production release\" is the FreeBSD-STABLE branch (\"-STABLE\") " "[<>]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:318 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:321 msgid "" "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 they are waiting for review or people to test one or more of " "their changes, they may be writing another change." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:324 msgid "" "As each commit represents an increment, this is a massively incremental " "model. The commits are in fact so frequent that during one year footnote:" "[The period from January 1st, 2004 to December 31st, 2004 was examined to " "find this number.] , 85427 commits were made, making a daily average of 233 " "commits." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:328 msgid "" "Within the \"code\" bracket in Jørgensen's model, each programmer has their " "own working style and follows their own development models. The bracket " "could very well have been called \"development\" 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:334 msgid "" "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)." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:337 msgid "" "It is important to notice the word \"change\". Most commits do not contain " "radical new features, but are maintenance updates." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:340 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:345 msgid "" "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:[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.]. 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:352 msgid "" "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:" "[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.] As design is a part of " "the \"Code\" 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:354 #, no-wrap msgid "Release branches" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:358 msgid "" "The releases of FreeBSD are 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:365 msgid "" "In the following release tree, arrows that follow one-another in a " "particular direction represent a branch. Boxes with full lines and diamonds " "represent official releases. Boxes with dotted lines represent the " "development branch at that time. Security branches are represented by " "ovals. Diamonds differ from boxes in that they represent a fork, meaning a " "place where a branch splits into two branches where one of the branches " "becomes a sub-branch. For example, at 4.0-RELEASE the 4.0-CURRENT branch " "split into 4-STABLE and 5.0-CURRENT. At 4.5-RELEASE, the branch forked off a " "security branch called RELENG_4_5." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:366 #, no-wrap msgid "The FreeBSD release tree" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/books/dev-model/_index.adoc:367 #, no-wrap msgid "Refer to table below for a screen-reader friendly version." msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:367 #, no-wrap msgid "branches.png" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:373 #, no-wrap msgid "Major release" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:374 #, no-wrap msgid "Forked from" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:376 #, no-wrap msgid "Following minor releases" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:377 #: documentation/content/en/books/dev-model/_index.adoc:397 #, no-wrap msgid "..." msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:381 #, no-wrap msgid "3.0 Current (development branch)" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:384 #, no-wrap msgid "Releng 3 branches: 3.0 Release to 3.5 Release, leading to 3.5.1 Release and the subsequent 3 Stable branch" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:385 #, no-wrap msgid "4.0 Current (development branch)" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:386 #, no-wrap msgid "3.1 Release" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:388 #, no-wrap msgid "Releng 4 branches: 4.1 Release to 4.6 Release (and 4.6.2 Release), then 4.7 Release to 4.11 Release (all starting at 4.3 Release also leading to a Releng_4_n branch), and the subsequent 4 Release branch" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:389 #, no-wrap msgid "5.0 Current (development branch)" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:390 #, no-wrap msgid "4.0 Release" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:392 #, no-wrap msgid "Releng 5 branches: 5.0 Release to 5.4 Release (all except 5.0 and 5.3 also leading to a Releng_5_n branch), and the subsequent 5 Release branch" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:393 #, no-wrap msgid "6.0 Current (development branch)" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:394 #, no-wrap msgid "5.3 Release" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:404 msgid "" "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. [<>]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:411 msgid "" "A \"major release\" is always made from the -CURRENT branch. However, the -" "CURRENT branch does not need to fork at that point in time, but can focus on " "stabilising. An example of this is that following 3.0-RELEASE, 3.1-RELEASE " "was also a continuation of the -CURRENT-branch, and -CURRENT did not become " "a true development branch until this version was released and the 3-STABLE " "branch was forked. When -CURRENT returns to becoming a development branch, " "it can only be followed by a major release. 5-STABLE is predicted to be " "forked off 5.0-CURRENT at around 5.3-RELEASE. It is not until 5-STABLE is " "forked that the development branch will be branded 6.0-CURRENT." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:413 msgid "" "A \"minor release\" is made from the -CURRENT branch following a major " "release, or from the -STABLE branch." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:416 msgid "" "Following and including, 4.3-RELEASEfootnote:[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.], when a minor release " "has been made, it becomes a \"security branch\". 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:" "[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.]" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:421 msgid "" "Each update to a security branch is called a \"patchlevel\". 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:423 #, no-wrap msgid "Model summary" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:426 msgid "" "To summarise, the development model of FreeBSD can be seen as the following " "tree:" msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:427 #, no-wrap msgid "The overall development model" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/books/dev-model/_index.adoc:428 #, no-wrap msgid "Refer to paragraphs below for a screen-reader friendly version." msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:428 #, no-wrap msgid "freebsd-code-model.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:431 msgid "" "The tree of the FreeBSD development with ongoing development efforts and " "continuous integration." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:435 msgid "" "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. Below the -STABLE " "branch are old, unsupported versions." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:439 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:446 msgid "" "Many committers have a special area of responsibility. These roles are " "called hats. These hats can be either project roles, such as public " "relations officer, or maintainer for a certain area of the code. Because " "this is a project where people give voluntarily of their spare time, people " "with assigned hats are not always available. They must therefore appoint a " "deputy that can perform the hat's role in their absence. The other option " "is to have the role held by a group." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:451 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:453 #, no-wrap msgid "Hats" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:456 #, no-wrap msgid "General Hats" msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:459 #, no-wrap msgid "Contributor" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:462 msgid "" "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. [<>]" msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:464 #, no-wrap msgid "Committer" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:469 msgid "" "A person who has the required privileges to add their code or documentation " "to the repository. A committer has made a commit within the past 12 " "months. [<>] An active " "committer is a committer who has made an average of one commit per month " "during that time." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:472 msgid "" "It is worth noting that there are no technical barriers to prevent someone, " "once having gained commit privileges to the main- or a sub-project, to make " "commits in parts of that project's source the committer did not specifically " "get permission to modify. However, when wanting to make modifications to " "parts a committer has not been involved in before, they should read the logs " "to see what has happened in this area before, and also read the MAINTAINERS " "file to see if the maintainer of this part has any special requests on how " "changes in the code should be made." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:474 #, no-wrap msgid "Core Team" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:480 msgid "" "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 of July 1st, 2004, core consisted of 9 members. Elections are " "held every two years." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:482 #, no-wrap msgid "Maintainership" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:486 msgid "" -"Maintainership means that that person is responsible for what is allowed to " +"Maintainership means that the person is responsible for what is allowed to " "go into that area of the code and has the final say should disagreements " "over the code occur. This involves proactive work aimed at stimulating " "contributions and reactive work in reviewing commits." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:489 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:492 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:494 msgid "" "Maintainership of a particular piece of code is a hat that is not held as a " "group." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:496 #, no-wrap msgid "Official Hats" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:501 msgid "" "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 list shows the responsibility " "lines and gives a description of each hat, including who it is held by." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:503 #, no-wrap msgid "Documentation project manager" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:506 msgid "" "<> architect is responsible for defining and " "following up documentation goals for the committers in the Documentation " "project, which they supervise." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:509 msgid "" "Hat held by: The DocEng team mailto:doceng@FreeBSD.org[doceng@FreeBSD.org]. " "The https://www.freebsd.org/internal/doceng/[ DocEng Charter]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:511 #, no-wrap msgid "Postmaster" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:515 msgid "" "The Postmaster is responsible for mail being correctly delivered to the " "committers' email address. They are 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:517 msgid "" "Hat currently held by: the Postmaster Team mailto:postmaster@FreeBSD." "org[postmaster@FreeBSD.org]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:519 #, no-wrap msgid "Release Coordination" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:522 msgid "The responsibilities of the Release Engineering Team are" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:524 msgid "" "Setting, publishing and following a release schedule for official releases" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:525 msgid "Documenting and formalising release engineering procedures" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:526 msgid "Creation and maintenance of code branches" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:527 msgid "" "Coordinating with the Ports and Documentation teams to have an updated set " "of packages and documentation released with the new releases" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:528 msgid "" "Coordinating with the Security team so that pending releases are not " "affected by recently disclosed vulnerabilities." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:530 msgid "" "Further information about the development process is available in the " "<> section." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:534 msgid "" "Hat held by: the Release Engineering team mailto:re@FreeBSD.org[re@FreeBSD." "org]. The https://www.freebsd.org/releng/charter/[ Release Engineering " "Charter]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:536 #, no-wrap msgid "Public Relations & Corporate Liaison" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:539 msgid "The Public Relations & Corporate Liaison's responsibilities are:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:541 msgid "" "Making press statements when happenings that are important to the FreeBSD " "Project happen." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:542 msgid "" "Being the official contact person for corporations that are working close " "with the FreeBSD Project." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:543 msgid "" "Take steps to promote FreeBSD within both the Open Source community and the " "corporate world." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:544 msgid "Handle the \"freebsd-advocacy\" mailing list." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:546 msgid "This hat is currently not occupied." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:548 #, no-wrap msgid "Security Officer" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:552 msgid "" "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 behavior when it " "comes to security." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:555 msgid "" "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 <> members, " "receive sensitive information about security issues. However, to create or " "implement a patch, the Security Officer has the Security Officer Team mailto:" "security-team@FreeBSD.org[security-team@FreeBSD.org] to help do the work." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:557 #, no-wrap msgid "Source Repository Manager" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:562 msgid "" "The Source Repository Manager is the only one who is allowed to directly " "modify the repository without using the <> tool. It is their " "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 SVN " "technical problem." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:564 msgid "" "Hat held by: the Source Repository Manager mailto:clusteradm@FreeBSD." "org[clusteradm@FreeBSD.org]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:566 #, no-wrap msgid "Election Manager" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:571 msgid "" "The Election Manager is responsible for the <> " "process. The manager is responsible for running and maintaining the " "election system, and is the final authority should minor unforeseen events " "happen in the election process. Major unforeseen events have to be " "discussed with the <>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:573 msgid "Hat held only during elections." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:575 #, no-wrap msgid "Web site Management" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:579 msgid "" "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 <> and acts " "as maintainer for the \"www\" tree." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:581 msgid "" "Hat held by: the FreeBSD Webmasters mailto:www@FreeBSD.org[www@FreeBSD.org]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:583 #, no-wrap msgid "Ports Manager" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:586 msgid "" "The Ports Manager acts as a liaison between <> and the " "core project, and all requests from the project should go to the ports " "manager." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:589 msgid "" "Hat held by: the Ports Management Team mailto:portmgr@FreeBSD." "org[portmgr@FreeBSD.org]. The https://www.freebsd.org/portmgr/charter/" "[Portmgr charter]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:591 #, no-wrap msgid "Standards" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:594 msgid "" "The Standards hat is responsible for ensuring that FreeBSD complies with the " "standards it is committed to , 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:596 msgid "" "Hat currently held by: Garrett Wollman mailto:wollman@FreeBSD." "org[wollman@FreeBSD.org]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:598 #, no-wrap msgid "Core Secretary" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:602 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:604 msgid "Hat currently held by: {bofh}." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:606 #, no-wrap msgid "Bugmeister" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:610 msgid "" "The Bugmeister 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. They supervise bugbusters." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:612 msgid "" "Hat currently held by: the Bugmeister Team mailto:bugmeister@FreeBSD." "org[bugmeister@FreeBSD.org]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:614 #, no-wrap msgid "Donations Liaison Officer" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:617 msgid "" "The task of the donations liaison officer is to match the developers with " "needs with people or organisations willing to make a donation." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:620 msgid "" "Hat held by: the Donations Liaison Office mailto:donations@FreeBSD." "org[donations@FreeBSD.org]. The https://www.freebsd.org/donations/" "[ Donations Liaison Charter]." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:622 #, no-wrap msgid "Admin" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:625 msgid "(Also called \"FreeBSD Cluster Admin\")" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:628 msgid "" "The admin team consists of the people responsible for administrating the " "computers that the project relies on for its distributed work and " "communication to be synchronised. It consists mainly of those people who " "have physical access to the servers." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:630 msgid "" "Hat held by: the Admin team mailto:admin@FreeBSD.org[admin@FreeBSD.org]." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:632 #, no-wrap msgid "Process dependent hats" msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:635 #, no-wrap msgid "Report originator" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:638 msgid "The person originally responsible for filing a Problem Report." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:640 #, no-wrap msgid "Bugbuster" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:643 msgid "" "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." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:645 #, no-wrap msgid "Mentor" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:648 msgid "" "A mentor is a committer who takes it upon them to introduce a new committer " "to the project, both in terms of ensuring the new committer's setup is " "valid, that the new committer knows the available tools required in their " "work, and that the new committer knows what is expected of them in terms of " "behavior." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:650 #, no-wrap msgid "Vendor" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:653 msgid "" "The person(s) or organisation whom external code comes from and whom patches " "are sent to." msgstr "" #. type: Title ==== #: documentation/content/en/books/dev-model/_index.adoc:655 #, no-wrap msgid "Reviewers" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:658 msgid "People on the mailing list where the request for review is posted." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:661 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:663 #, no-wrap msgid "Processes" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:666 #, no-wrap msgid "Adding new and removing old committers" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:671 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:674 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:677 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:680 msgid "" "When a contributor is given committer status, they are assigned a mentor. " "The committer who recommended the new committer will, in the general case, " "take it upon themselves to be the new committers mentor." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:684 msgid "" "When a contributor is given their commit bit, a <>-signed email is " "sent from either <>, <>, 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, <> public key, and PGP key from the " "new committer and sends them to <>. When the new account is " "created, the mentor activates the commit bit and guides the new committer " "through the rest of the initial process." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:685 #, no-wrap msgid "Process summary: adding a new committer" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/books/dev-model/_index.adoc:686 #: documentation/content/en/books/dev-model/_index.adoc:701 #: documentation/content/en/books/dev-model/_index.adoc:744 #: documentation/content/en/books/dev-model/_index.adoc:795 #: documentation/content/en/books/dev-model/_index.adoc:917 #, no-wrap msgid "Refer to paragraph below for a screen-reader friendly version." msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:686 #, no-wrap msgid "proc-add-committer.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:693 msgid "" "When a contributor sends a piece of code, the receiving committer may choose " "to recommend that the contributor is given commit privileges. If they " "recommend this to core, core will vote on this recommendation. If the vote " "is in favour, a mentor is assigned the new committer and the new committer " "has to email their details to the administrators for an account to be " "created. After this, the new committer is all set to make their first " "commit. By tradition, this is by adding their name to the committers list." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:696 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:699 msgid "" "There are, however, no automatic procedures for doing this. For reactions " "concerning commit privileges not triggered by time, see <>." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:700 #, no-wrap msgid "Process summary: removing a committer" msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:701 #, no-wrap msgid "proc-rm-committer.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:705 msgid "" "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 and their account removed by the administrators." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:708 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:710 msgid "Roles in this process:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:712 #: documentation/content/en/books/dev-model/_index.adoc:804 #: documentation/content/en/books/dev-model/_index.adoc:958 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:713 #: documentation/content/en/books/dev-model/_index.adoc:763 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:714 #: documentation/content/en/books/dev-model/_index.adoc:762 #: documentation/content/en/books/dev-model/_index.adoc:805 #: documentation/content/en/books/dev-model/_index.adoc:959 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:715 #: documentation/content/en/books/dev-model/_index.adoc:928 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:716 msgid "<>" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:720 #, no-wrap msgid "Committing code" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:725 msgid "" "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 \"committer\". Committers commit either code " "written by themselves, code submitted to them, or code submitted through a " "<>." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:731 msgid "" "When code is written by the developer that is non-trivial, they 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, " "they should ensure it compiles correctly with the entire tree and that all " "relevant tests run. This is called \"pre-commit test\". When contributed " "code is received, it should be reviewed by the committer and tested the same " "way." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:734 msgid "" "When a change is committed to a part of the source that has been contributed " "from an outside <>, 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:739 msgid "" "After the code has been available for review and no further changes are " "necessary, the code is committed into the development branch, -CURRENT. If " "the change applies for the -STABLE branch or the other branches as well, a " "\"Merge From Current\" (\"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 them to commit " "it to the -STABLE branch (and possibly security branches as well). Only " "security critical changes should be merged to security branches." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:742 msgid "" "Delaying the commit to -STABLE and other branches allows for \"parallel " "debugging\" 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." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:743 #, no-wrap msgid "Process summary: A committer commits code" msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:744 #, no-wrap msgid "proc-commit.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:752 msgid "" "When a committer has written a piece of code and wants to commit it, they " "first need 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, they 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 then " "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, they can choose to implement or ignore the patch." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:753 #, no-wrap msgid "Process summary: A contributor commits code" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/books/dev-model/_index.adoc:754 #, no-wrap msgid "Refer to paragraphs below and above for a screen-reader friendly version." msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:754 #, no-wrap msgid "proc-contrib.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:758 msgid "" "The difference when a contributor makes a code contribution is that they " "submit the code through the Bugzilla interface. This report is picked up by " "the maintainer who reviews the code and commits it." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:760 msgid "Hats included in this process are:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:764 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:765 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:767 msgid "" "[<>] [<>]" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:769 #, no-wrap msgid "Core election" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:774 msgid "" "Core elections are held at least every two years. footnote:[The first Core " "election was held September 2000] 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:776 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:781 msgid "" "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 http://" "election.uk.freebsd.org/candidates.html[candidates list]. When writing " "their election statements, the candidates must answer a few standard " "questions submitted by the election manager." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:784 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:787 msgid "" "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 \"developers\" mailing list that is available to all committers." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:789 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:791 msgid "" "Should there be a voting tie, this will be resolved by the new, " "unambiguously elected core members." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:793 msgid "" "Votes and candidate statements are archived, but the archives are not " "publicly available." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:794 #, no-wrap msgid "Process summary: Core elections" msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:795 #, no-wrap msgid "proc-elections.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:800 msgid "" "Core announces the election and selects an election manager who 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:802 msgid "Hats in core elections are:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:806 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:808 msgid "" "[<>] [<>] " "[<>]" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:810 #, no-wrap msgid "Development of new features" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:817 msgid "" "Within the project there are sub-projects that are working on new features. " "These projects are generally done by one person [<>]. 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:823 msgid "" "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 their time between the " "request and their 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 <> tool." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:828 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:831 msgid "" "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 prioritisation 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:838 msgid "" "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:[More and more tests are " "however performed when building the system (make world). These tests are " "however a very new addition and no systematic framework for these tests have " "yet been created.]" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:840 #, no-wrap msgid "Maintenance" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:847 msgid "" "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:[sendmail and " "named are examples of code that has been merged from other platforms.] 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:850 msgid "" "The main bulk of work that is put into the FreeBSD project is maintenance. " "[<>] has made a figure showing the life " "cycle of changes." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:888 msgid "" "Here \"development release\" refers to the -CURRENT branch while " "\"production release\" refers to the -STABLE branch. The \"pre-commit test" "\" 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. \"Parallel " "debugging\" is the functional testing that can trigger more review, and " "debugging when the code is included in the -CURRENT branch." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:895 msgid "" "As of this writing, there were 269 committers in the project. When they " "commit a change to a branch, that constitutes a new release. It is very " "common for users in the community to track a particular branch. The " "immediate existence of a new release makes the changes widely available " "right away and allows for rapid feedback from the community. This also " "gives the community the response time they expect on issues that are of " "importance to them. This makes the community more engaged, and thus allows " "for more and better feedback that again spurs more maintenance and " "ultimately should create a better product." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:897 msgid "" "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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:899 #, no-wrap msgid "Problem reporting" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:904 msgid "" "Before FreeBSD 10, FreeBSD included a problem reporting tool called `send-" "pr`. Problems include bug reports, feature requests, feature enhancements " "and notices of new versions of external software that are included in the " "project. Although `send-pr` is available, users and developers are " "encouraged to submit issues using our https://bugs.freebsd.org/submit/" "[ problem report form]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:915 msgid "" "Problem reports are sent to an email address where it is inserted into the " "Problem Reports maintenance database. A <> 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 " "<>. 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." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:916 #, no-wrap msgid "Process summary: problem reporting" msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:917 #, no-wrap msgid "proc-pr.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:923 msgid "" "A problem is reported by the report originator. It is then classified by a " "bugbuster and handed to the correct maintainer. They verify the problem and " "discuss the problem with the originator until they have enough information " "to create a working patch. This patch is then committed and the problem " "report is closed." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:925 msgid "The roles included in this process are:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:927 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:929 msgid "<>" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:931 msgid "" "[<>]. [<>]" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:933 #, no-wrap msgid "Reacting to misbehavior" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:939 msgid "" "[<>] 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 misbehavior. They " "specify what actions will result in how long a suspension of the committer's " "commit privileges." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:941 msgid "" "Committing during code freezes without the approval of the Release " "Engineering team - 2 days" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:942 msgid "Committing to a security branch without approval - 2 days" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:943 msgid "Commit wars - 5 days to all participating parties" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:944 msgid "Impolite or inappropriate behavior - 5 days" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:951 msgid "" "For the suspensions to be efficient, any single core member can implement a " "suspension before discussing it on the \"core\" 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 \"developers\" mailing " "list, a list available to committers only." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:954 msgid "" "It is important that you cannot be suspended for making technical errors. " "All penalties come from breaking social etiquette." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:956 msgid "Hats involved in this process:" msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:961 #, no-wrap msgid "Release engineering" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:967 msgid "" "The FreeBSD project has a Release Engineering 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 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:974 msgid "" "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 they " "find that the changes are not suitable to be included in the release." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:976 msgid "There are three different kinds of releases:" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:978 msgid "" ".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" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:979 msgid "" ".X releases are releases of the -STABLE branch. They are scheduled to come " "out every 4 months." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:980 msgid "" ".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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:989 msgid "" "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 CD-" "ROM images. However, the release is not considered \"really released\" " "until a <>-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:[Many commercial vendors use these images to " "create CD-ROMs that are sold in retail outlets.]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:998 msgid "" "The releases of the -CURRENT-branch (that is, all releases that end with " "\".0\") 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1000 #, no-wrap msgid "*.0 releases go into their own branch and are aimed mainly at early adopters. The branch then goes through a period of stabilisation, and it is not until the <> decides the demands to stability have been satisfied that the branch becomes -STABLE and -CURRENT targets the next major version. While this for the majority has been with *.1 versions, this is not a demand. \n" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1005 msgid "" "Most releases are made when a given date that has been deemed a long enough " "time since the previous release comes. A target is set for having major " "releases every 18 months and minor releases every 4 months. The user " "community has made it very clear that security and stability cannot be " "sacrificed by self-imposed deadlines and target release dates. For slips of " "time not to become too long with regards to security and stability issues, " "extra discipline is required when committing changes to -STABLE." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1007 msgid "Make release schedule" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1008 msgid "Feature freeze" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1009 msgid "Code freeze" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1010 msgid "Make branch" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1011 msgid "Release candidate" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1012 msgid "" "Stabilize release (loop back to previous step as many times as necessary; " "when release is considered stable, proceed with next step)" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1013 msgid "Build packages" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1014 msgid "Warn mirrors" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1015 msgid "Publish release" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1017 msgid "[<>]" msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:1019 #, no-wrap msgid "Tools" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1023 msgid "" "The major support tools for supporting the development process are Bugzilla, " "Mailman, and OpenSSH. These are externally developed tools and are commonly " "used in the open source world." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1025 #, no-wrap msgid "Subversion (SVN)" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1029 msgid "" "Subversion (\"SVN\") is a system to handle multiple versions of text files " "and tracking who committed what changes and why. A project lives within a " "\"repository\" and different versions are considered different \"branches\"." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1031 #, no-wrap msgid "Bugzilla" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1037 msgid "" "Bugzilla 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 its web interface to send \"Problem Reports\" " "to the project's central Bugzilla server. The committers also have web and " "command-line clients." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1039 #, no-wrap msgid "Mailman" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1046 msgid "" "Mailman is a program that automates the management of mailing lists. The " "FreeBSD Project uses it to run 16 general lists, 60 technical lists, 4 " "limited lists and 5 lists with SVN commit logs. It is also used for many " "mailing lists set up and used by other people and projects in the FreeBSD " "community. General lists are lists for the general public, technical lists " "are mainly for the development of specific areas of interest, and closed " "lists are for internal communication not intended for the general public. " "The majority of all the communication in the project goes through these 85 " "lists [<>, Appendix C]." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1048 #, no-wrap msgid "Pretty Good Privacy" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1053 msgid "" "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 to 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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1055 #, no-wrap msgid "Secure Shell" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1062 msgid "" "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." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:1064 #, no-wrap msgid "Sub-projects" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1067 msgid "" "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." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1069 #, no-wrap msgid "The Ports Subproject" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1073 msgid "" "A \"port\" 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 has grown at a tremendous rate, as shown by the " "following figure." msgstr "" #. type: Block title #: documentation/content/en/books/dev-model/_index.adoc:1074 #, no-wrap msgid "Number of ports added between 1996 and 2008 [[fig-ports]]" msgstr "" #. type: Positional ($1) AttributeList argument for macro 'image' #: documentation/content/en/books/dev-model/_index.adoc:1075 #, no-wrap msgid "Refer to tables below for a screen-reader friendly version." msgstr "" #. type: Target for macro image #: documentation/content/en/books/dev-model/_index.adoc:1075 #, no-wrap msgid "portsstatus.png" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1079 msgid "" "<> shows the number of ports available to FreeBSD in the period " "1995 to 2008. It looks like the curve has first grown exponentially, and " "then from the middle of 2001 to the middle of 2007 grown linearly at a rate " "of about 2000 ports/year, before its growth rate gets lower." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1081 msgid "Approximate dates each multiple of 1000 ports is reached" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1086 #, no-wrap msgid "Number of ports" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1088 #, no-wrap msgid "Approximate date" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1089 #, no-wrap msgid "1000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1091 #, no-wrap msgid "Late 1997" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1092 #: documentation/content/en/books/dev-model/_index.adoc:1163 #: documentation/content/en/books/dev-model/_index.adoc:1164 #, no-wrap msgid "2000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1094 #, no-wrap msgid "Late 1998" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1095 #, no-wrap msgid "3000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1097 #, no-wrap msgid "Early 2000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1098 #, no-wrap msgid "4000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1100 #, no-wrap msgid "Late 2000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1101 #, no-wrap msgid "5000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1103 #, no-wrap msgid "Mid 2001" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1104 #, no-wrap msgid "6000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1106 #, no-wrap msgid "4th quarter of 2001" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1107 #, no-wrap msgid "7000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1109 #, no-wrap msgid "Mid 2002" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1110 #, no-wrap msgid "8000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1112 #, no-wrap msgid "4th quarter of 2002" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1113 #, no-wrap msgid "9000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1115 #, no-wrap msgid "Mid 2003" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1116 #, no-wrap msgid "10000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1118 #, no-wrap msgid "End of 2003" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1119 #, no-wrap msgid "11000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1121 #, no-wrap msgid "Mid 2004" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1122 #, no-wrap msgid "12000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1124 #, no-wrap msgid "End of 2004" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1125 #, no-wrap msgid "13000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1127 #, no-wrap msgid "Mid 2005" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1128 #: documentation/content/en/books/dev-model/_index.adoc:1184 #, no-wrap msgid "14000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1130 #, no-wrap msgid "Early 2006" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1131 #, no-wrap msgid "15000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1133 #, no-wrap msgid "Mid 2006" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1134 #, no-wrap msgid "16000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1136 #, no-wrap msgid "3rd quarter 2006" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1137 #, no-wrap msgid "17000" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1138 #, no-wrap msgid "2nd quarter 2007" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1141 msgid "Approximate number of ports at the start of each year" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1146 #, no-wrap msgid "Year" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1148 #, no-wrap msgid "Approximate number of ports" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1149 #, no-wrap msgid "1995" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1151 #, no-wrap msgid "100" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1152 #, no-wrap msgid "1996" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1154 #, no-wrap msgid "300" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1155 #, no-wrap msgid "1997" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1157 #, no-wrap msgid "700" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1158 #, no-wrap msgid "1998" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1160 #, no-wrap msgid "1200" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1161 #, no-wrap msgid "1999" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1166 #, no-wrap msgid "2900" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1167 #, no-wrap msgid "2001" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1169 #, no-wrap msgid "4300" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1170 #, no-wrap msgid "2002" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1172 #, no-wrap msgid "6200" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1173 #, no-wrap msgid "2003" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1175 #, no-wrap msgid "8100" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1176 #, no-wrap msgid "2004" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1178 #, no-wrap msgid "10050" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1179 #, no-wrap msgid "2005" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1181 #, no-wrap msgid "12100" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1182 #, no-wrap msgid "2006" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1185 #, no-wrap msgid "2007" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1187 #, no-wrap msgid "16200" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1188 #, no-wrap msgid "2008" msgstr "" #. type: Table #: documentation/content/en/books/dev-model/_index.adoc:1189 #, no-wrap msgid "17900" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1193 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1196 msgid "" "Ports has its own core team with the <> 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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1200 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1203 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1205 msgid "" "For efficiency of communication, teams depending on Ports, such as the " "release engineering team, have their own ports liaisons." msgstr "" #. type: Title === #: documentation/content/en/books/dev-model/_index.adoc:1207 #, no-wrap msgid "The FreeBSD Documentation Project" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1212 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1214 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1216 msgid "" "The main tasks in the Documentation project are to work on current projects " "in the \"FreeBSD Documentation Set\", and translate the documentation to " "other languages." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1220 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1222 msgid "" "Like the ports sub-project, the Documentation project can appoint " "documentation committers without FreeBSD Core's approval. [<>]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1225 msgid "" "The Documentation project has extref:{fdp-primer}[a primer]. This is used " "both to introduce new project members to the standard tools and syntaxes and " "to act as a reference when working on the project." msgstr "" #. type: Title == #: documentation/content/en/books/dev-model/_index.adoc:1230 #, no-wrap msgid "References" msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1234 msgid "" "[Brooks, 1995] Frederick P. Brooks. Copyright © 1975, 1995 Pearson Education " "Limited. 0201835959. Addison-Wesley Pub Co. The Mythical Man-Month. Essays " "on Software Engineering, Anniversary Edition (2nd Edition)." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1237 msgid "" "[Saers, 2003] Niklas Saers. Copyright © 2003. A project model for the " "FreeBSD Project. Candidatus Scientiarum thesis. http://niklas.saers.com/" "thesis." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1240 msgid "" "[Jørgensen, 2001] Niels Jørgensen. Copyright © 2001. Putting it All in the " "Trunk. Incremental Software Development in the FreeBSD Open Source Project. " "http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1243 msgid "" "[PMI, 2000] Project Management Institute. Copyright © 1996, 2000 Project " "Management Institute. 1-880410-23-0. Project Management Institute. Newtown " "Square Pennsylvania USA . PMBOK Guide. A Guide to the Project Management " "Body of Knowledge, 2000 Edition." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1246 msgid "" "[FreeBSD, 2000A] Copyright © 2002 The FreeBSD Project. Core Bylaws. https://" "www.freebsd.org/internal/bylaws/." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1249 msgid "" "[FreeBSD, 2002A] Copyright © 2002 The FreeBSD Documentation Project. FreeBSD " "Developer's Handbook. extref:{developers-handbook}[Developers Handbook]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1252 msgid "" "[FreeBSD, 2002B] Copyright © 2002 The FreeBSD Project. Core team election " "2002. http://election.uk.freebsd.org/candidates.html." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1255 msgid "" "[FreeBSD, 2002C] Dag-Erling Smørgrav and Hiten Pandya. Copyright © 2002 The " "FreeBSD Documentation Project. The FreeBSD Documentation Project. Problem " "Report Handling Guidelines. extref:{pr-guidelines}[Problem Report Handling " "Guidelines]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1258 msgid "" "[FreeBSD, 2002D] Dag-Erling Smørgrav. Copyright © 2002 The FreeBSD " "Documentation Project. The FreeBSD Documentation Project. Writing FreeBSD " "Problem Reports. extref:{problem-reports}[Writing FreeBSD Problem Reports]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1261 msgid "" "[FreeBSD, 2001] Copyright © 2001 The FreeBSD Documentation Project. The " "FreeBSD Documentation Project. Committers Guide. extref:{committers-guide}" "[Committer's Guide]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1264 msgid "" "[FreeBSD, 2002E] Murray Stokely. Copyright © 2002 The FreeBSD Documentation " "Project. The FreeBSD Documentation Project. FreeBSD Release Engineering. " "extref:{releng}[FreeBSD Release Engineering]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1267 msgid "" "[FreeBSD, 2003A] The FreeBSD Documentation Project. FreeBSD Handbook. extref:" "{handbook}[FreeBSD Handbook]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1270 msgid "" "[FreeBSD, 2002F] Copyright © 2002 The FreeBSD Documentation Project. The " "FreeBSD Documentation Project. Contributors to FreeBSD. extref:{contributors}" "[Contributors to FreeBSD]." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1273 msgid "" "[FreeBSD, 2002G] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. " "Core team elections 2002. http://election.uk.freebsd.org." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1276 msgid "" "[FreeBSD, 2002H] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. " "Commit Bit Expiration Policy. 2002/04/06 15:35:30. https://www.freebsd.org/" "internal/expire-bits/." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1279 msgid "" "[FreeBSD, 2002I] Copyright © 2002 The FreeBSD Project. The FreeBSD Project. " "New Account Creation Procedure. 2002/08/19 17:11:27. https://www.freebsd.org/" "internal/new-account/." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1282 msgid "" "[FreeBSD, 2003B] Copyright © 2002 The FreeBSD Documentation Project. The " "FreeBSD Documentation Project. FreeBSD DocEng Team Charter. 2003/03/16 " "12:17. https://www.freebsd.org/internal/doceng/." msgstr "" #. type: Plain text #: documentation/content/en/books/dev-model/_index.adoc:1284 msgid "" "[Lehey, 2002] Greg Lehey. Copyright © 2002 Greg Lehey. Greg Lehey. Two years " "in the trenches. The evolution of a software project. http://www.lemis.com/" "grog/In-the-trenches.pdf." msgstr ""