svn commit: r54087 - head/en_US.ISO8859-1/books/dev-model
Benedict Reuschling
bcr at FreeBSD.org
Fri May 1 10:15:03 UTC 2020
Author: bcr
Date: Fri May 1 10:15:03 2020
New Revision: 54087
URL: https://svnweb.freebsd.org/changeset/doc/54087
Log:
A number of (much needed) updates and corrections to the
dev-model book:
- Make pronouns truly gender-agnostic
- Correct typos and minor grammar errors
- Update number of ports vs. time graph to a less outdated version
(from [1])
- Enhance screenreader friendliness of pictures
- Remove reference to deleted image
- Add link to FDP primer
Thanks to Pau Amma for working on a patch and submitting it
to us.
[1] https://web.archive.org/web/20121223081637if_/http://www.freebsd.org/ports/growth/status.png
PR: 241814
Submitted by: pauamma_gundo.com
Reviewed by: debdrub, bcr, allanjude
Approved by: bcr
Differential Revision: https://reviews.freebsd.org/D24321
Modified:
head/en_US.ISO8859-1/books/dev-model/Makefile
head/en_US.ISO8859-1/books/dev-model/book.xml
Modified: head/en_US.ISO8859-1/books/dev-model/Makefile
==============================================================================
--- head/en_US.ISO8859-1/books/dev-model/Makefile Fri May 1 08:44:02 2020 (r54086)
+++ head/en_US.ISO8859-1/books/dev-model/Makefile Fri May 1 10:15:03 2020 (r54087)
@@ -15,17 +15,12 @@ SRCS= book.xml
IMAGES_EN= branches.png
IMAGES_EN+= freebsd-code-model.png
-IMAGES_EN+= hats-overview.png
-IMAGES_EN+= maintenance.png
-IMAGES_EN+= orghierarchy.png
-IMAGES_EN+= orghierarchy2.png
IMAGES_EN+= portsstatus.png
IMAGES_EN+= proc-add-committer.png
IMAGES_EN+= proc-commit.png
IMAGES_EN+= proc-contrib.png
IMAGES_EN+= proc-elections.png
IMAGES_EN+= proc-pr.png
-IMAGES_EN+= proc-releng.png
IMAGES_EN+= proc-rm-committer.png
DOC_PREFIX?= ${.CURDIR}/../../..
Modified: head/en_US.ISO8859-1/books/dev-model/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/dev-model/book.xml Fri May 1 08:44:02 2020 (r54086)
+++ head/en_US.ISO8859-1/books/dev-model/book.xml Fri May 1 10:15:03 2020 (r54087)
@@ -41,6 +41,12 @@
</copyright>
<revhistory>
<revision>
+ <revnumber>1.6</revnumber>
+ <date>November, 2019</date>
+ <revremark>Style revisions, accessibility enhancements,
+ and statistics updates throughout the book.</revremark>
+ </revision>
+ <revision>
<revnumber>1.5</revnumber>
<date>October, 2014</date>
<revremark>Remove mention of GNATS which is no longer
@@ -289,10 +295,34 @@
</para>
<para>
- <figure>
- <title>The FreeBSD Project's structure</title>
- <mediaobject><imageobject><imagedata fileref="orghierarchy"/></imageobject></mediaobject>
- </figure>
+ The FreeBSD Project's structure (in order of descending authority)
+ <informaltable pgwide="1">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Group</entry>
+ <entry>Number of people</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Core members</entry>
+ <entry>9</entry>
+ </row>
+
+ <row>
+ <entry>Committers</entry>
+ <entry>269</entry>
+ </row>
+
+ <row>
+ <entry>Contributors</entry>
+ <entry>~3000</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
@@ -306,7 +336,7 @@
The main resource in the FreeBSD community is its developers: the
committers and contributors. It is with their contributions that the
project can move forward. Regular developers are referred to as contributors.
- As by January 1st, 2003, there are an estimated 5500
+ As of January 1st, 2003, there are an estimated 5500
contributors on the project.
<!--
Contributors = people submitting PRs + people submitting code - overlap.
@@ -344,13 +374,65 @@
</para>
<para>
- This split changes our triangle to look like this:
+ This split changes our table to look like this:
</para>
<para>
- <figure>
- <title>The FreeBSD Project's structure with committers in categories</title>
- <mediaobject><imageobject><imagedata fileref="orghierarchy2"/></imageobject></mediaobject>
- </figure>
+ The FreeBSD Project's structure with committers in categories
+ <informaltable pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Group</entry>
+ <entry>Category</entry>
+ <entry>Number of people</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Core members</entry>
+ <entry></entry>
+ <entry>9</entry>
+ </row>
+
+ <row>
+ <entry>Committers</entry>
+ <entry>Kernel</entry>
+ <entry>56</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+ <entry>Userland</entry>
+ <entry>50</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+ <entry>Docs</entry>
+ <entry>9</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+ <entry>Ports</entry>
+ <entry>120</entry>
+ </row>
+
+ <row>
+ <entry></entry>
+ <entry>Total</entry>
+ <entry>269</entry>
+ </row>
+
+ <row>
+ <entry>Contributors</entry>
+ <entry></entry>
+ <entry>~3000</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
Number of committers per area has been determined by going through
@@ -365,12 +447,12 @@
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
+ are involved only with one sub-project,
and committers who commit to different parts
of the code, including sub-projects.
Because some committers work on different parts, the total
- number in the committers section of the triangle is higher than
- in the above triangle.
+ number in the committers section of the table is higher than
+ in the above table.
</para>
<para>
@@ -382,7 +464,7 @@
see all the consequences of a kernel change, demands
developers with a relative full understanding of the
kernel. Multiple development efforts in the kernel also
- requires a closer coordination than userland applications do.
+ require a closer coordination than userland applications do.
</para>
<para>
@@ -441,10 +523,55 @@
</para>
<para>
- <figure>
- <title>Jørgenssen's model for change integration</title>
- <mediaobject><imageobject><imagedata fileref="maintenance"/></imageobject></mediaobject>
- </figure>
+ Jørgenssen's model for change integration
+ <informaltable pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Stage</entry>
+ <entry>Next if successful</entry>
+ <entry>Next if unsuccessful</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>code</entry>
+ <entry>review</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>review</entry>
+ <entry>pre-commit test</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>pre-commit test</entry>
+ <entry>development release</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>development release</entry>
+ <entry>parallel debugging</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>parallel debugging</entry>
+ <entry>production release</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>production release</entry>
+ <entry></entry>
+ <entry>code</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
@@ -472,8 +599,8 @@
individually, meaning that this model is used in parallel by
many developers on the different ongoing development efforts. A
developer can also be working on multiple changes, so that while
- he is waiting for review or people to test one or more of his
- changes, he may be writing another change.
+ they are waiting for review or people to test one or more of their
+ changes, they may be writing another change.
</para>
<para>
@@ -492,7 +619,7 @@
<para>
Within the <quote>code</quote> bracket in Jørgensen's
- figure, each programmer has his own working style and follows his
+ model, each programmer has their own working style and follows their
own development models. The bracket could very well have been
called <quote>development</quote> as it includes requirements
gathering and analysis, system and detailed design,
@@ -584,7 +711,7 @@
<title>Release branches</title>
<para>
- The releases of FreeBSD is best illustrated by a tree with many
+ 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.
@@ -608,10 +735,84 @@
<para>
<figure>
<title>The FreeBSD release tree</title>
- <mediaobject><imageobject><imagedata fileref="branches"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="branches"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to table below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
+
<para>
+ <informaltable pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Major release</entry>
+ <entry>Forked from</entry>
+ <entry>Following minor releases</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>…</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>3.0 Current (development branch)</entry>
+ <entry></entry>
+ <entry>Releng 3 branches: 3.0 Release to
+ 3.5 Release, leading to 3.5.1 Release
+ and the subsequent 3 Stable branch
+ </entry>
+ </row>
+
+ <row>
+ <entry>4.0 Current (development branch)</entry>
+ <entry>3.1 Release</entry>
+ <entry>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
+ </entry>
+ </row>
+
+ <row>
+ <entry>5.0 Current (development branch)</entry>
+ <entry>4.0 Release</entry>
+ <entry>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
+ </entry>
+ </row>
+
+ <row>
+ <entry>6.0 Current (development branch)</entry>
+ <entry>5.3 Release</entry>
+ </row>
+
+ <row>
+ <entry>…</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+
+ <para>
The latest -CURRENT version
is always referred to as -CURRENT, while the latest -STABLE
release is always referred to as -STABLE. In this figure,
@@ -689,21 +890,29 @@
<para>
<figure>
<title>The overall development model</title>
- <mediaobject><imageobject><imagedata fileref="freebsd-code-model"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="freebsd-code-model"/></imageobject>
+ <textobject><literallayout class="monospaced"></literallayout></textobject>
+ <textobject>
+ <phrase>Refer to paragraphs below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
+
<para>
The tree of the FreeBSD development with ongoing development
efforts and continuous integration.
</para>
-
<para>
The tree symbolises the release versions with major versions
spawning new main branches and minor versions being versions of
the main branch. The top branch is the -CURRENT branch where all
new development is integrated, and the -STABLE branch is the
- branch directly below it.
+ branch directly below it. Below the -STABLE branch are old,
+ unsupported versions.
</para>
<para>
@@ -730,7 +939,7 @@
code. Because this is a project where people give voluntarily of
their spare time, people with assigned hats are not always
available. They must therefore appoint a deputy that can perform
- the hat's role in his or her absence. The other option is to have
+ the hat's role in their absence. The other option is to have
the role held by a group.
</para>
@@ -763,7 +972,7 @@
<section xml:id="role-committer" xreflabel="Committer">
<title>Committer</title>
<para>
- A person who has the required privileges to add his code or documentation to the
+ A person who has the required privileges to add their code or documentation to the
repository.
<!--
Note that there are people with commit privileges that used
@@ -782,17 +991,17 @@
parts of that project's source the committer did not specifically get
permission to modify. However, when wanting to make
modifications to parts a committer has not been involved in
- before, he/she should read the logs to see what has happened
- in this area before, and also read the MAINTAINER file to see if
+ 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
+ changes in the code should be made.
<!--
Also, since
<xref linkend="sub-project-ports"/> is allowed to give commit
privileges without approval from core, a committer who has
- gained his privileges through contributing to the ports
+ gained their privileges through contributing to the ports
sub-project should be careful and
- have his changes approved before committing anything outside
+ have their changes approved before committing anything outside
the ports tree.
-->
</para>
@@ -809,7 +1018,7 @@
well-defined hats, and is the final arbiter of decisions involving
which way the project should be heading.
- As by July 1st, 2004, core consisted of 9 members.
+ As of July 1st, 2004, core consisted of 9 members.
Elections are held every two years.
</para>
@@ -862,33 +1071,20 @@
The official hats in the FreeBSD Project are hats that are more
or less formalised and mainly administrative roles. They have
the authority and responsibility for their area. The following
- illustration shows the responsibility lines. After this follows
+ list shows the responsibility lines and gives
a description of each hat, including who it is held by.
</para>
- <para>
- <figure>
- <title>Overview of official hats</title>
- <mediaobject><imageobject><imagedata fileref="hats-overview"/></imageobject></mediaobject>
- </figure>
- </para>
- <para>
- All boxes consist of groups of committers, except for the
- dotted boxes where the holders are not necessarily committers. The
- flattened circles are sub-projects and consist of both
- committers and non-committers of the main project.
- </para>
-
-
<section xml:id="role-doc-manager" xreflabel="Documentation project architect">
<title>Documentation project manager</title>
<para>
<xref linkend="sub-project-documentation"/>
architect is responsible for
defining and following up documentation goals for the
- committers in the Documentation project.
+ committers in the Documentation project, which they
+ supervise.
</para>
<para>
@@ -904,7 +1100,7 @@
<title>Postmaster</title>
<para>
The Postmaster is responsible for mail being correctly
- delivered to the committers' email address. He is also
+ 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.
@@ -1014,7 +1210,7 @@
The Source Repository Manager is the only one who is allowed
to directly modify the repository without using the
<xref linkend="tool-svn"/> tool.
- It is his/her
+ 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
@@ -1114,7 +1310,7 @@
<para>
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.
+ are correctly categorised and that there are no invalid entries. They supervise bugbusters.
</para>
<para>
Hat currently held by:
@@ -1129,13 +1325,14 @@
the donations liaison officer is to match
the developers with needs with people or
organisations willing to make a
- donation. The Donations Liaison Charter is
- available
- <link xlink:href="https://www.freebsd.org/donations/">here</link>
+ donation.
</para>
<para>
Hat held by:
the Donations Liaison Office <email>donations at FreeBSD.org</email>.
+ The
+ <link xlink:href="https://www.freebsd.org/donations/">
+ Donations Liaison Charter</link>.
</para>
</section>
@@ -1191,12 +1388,12 @@
<section xml:id="role-mentor" xreflabel="Mentor">
<title>Mentor</title>
<para>
- A mentor is a committer who takes it upon him/her to
+ 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 committers setup is valid,
+ ensuring the new committer's setup is valid,
that the new committer knows the available tools required in
- his/her work and that the
- new committer knows what is expected of him/her in terms of
+ their work, and that the
+ new committer knows what is expected of them in terms of
behavior.
</para>
</section>
@@ -1260,20 +1457,20 @@
</para>
<para>
- When a contributor is given committer status, he is
+ 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
- himself to be the new committers mentor.
+ themselves to be the new committers mentor.
</para>
<para>
- When a contributor is given his commit bit, a <xref linkend="tool-pgp"/>-signed email is sent
+ When a contributor is given their commit bit, a <xref linkend="tool-pgp"/>-signed email is sent
from either <xref linkend="role-core-secretary"/>,
- <xref linkend="role-ports-manager"/> or nik at freebsd.org to both
- admins at freebsd.org, the assigned mentor, the new committer and
+ <xref linkend="role-ports-manager"/>, or nik at freebsd.org to both
+ admins at freebsd.org, the assigned mentor, the new committer, and
core confirming the approval of a new account. The mentor then
- gathers a password line, <xref linkend="tool-ssh2"/> public key and PGP key from the
+ gathers a password line, <xref linkend="tool-ssh2"/> public key, and PGP key from the
new committer and sends them to <xref linkend="role-admin"/>. When the new account is created, the
mentor activates the commit bit and guides the new committer
through the rest of the initial process.
@@ -1282,20 +1479,28 @@
<para>
<figure>
<title>Process summary: adding a new committer</title>
- <mediaobject><imageobject><imagedata fileref="proc-add-committer"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-add-committer"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject><phrase>Refer to paragraph below
+ for a screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
When a contributor sends a piece of code, the receiving
committer may choose to recommend that the contributor is
- given commit privileges. If he recommends this to core,
- they will vote on this recommendation. If they vote in
+ 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 his details to the administrators
+ 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 his first commit. By
- tradition, this is by adding his name to the committers list.
+ committer is all set to make their first commit. By
+ tradition, this is by adding their name to the committers list.
</para>
<para>
@@ -1314,7 +1519,16 @@
<para>
<figure>
<title>Process summary: removing a committer</title>
- <mediaobject><imageobject><imagedata fileref="proc-rm-committer"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-rm-committer"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to paragraph below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
@@ -1322,7 +1536,8 @@
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.
+ bits revoked and their account removed by the
+ administrators.
</para>
<para>
@@ -1370,16 +1585,16 @@
frequent processes in the FreeBSD project and will usually
happen many times a day. Committing of code can only be done
by a <quote>committer</quote>. Committers commit either code
- written by themselves, code submitted to them or code
+ written by themselves, code submitted to them, or code
submitted through a <link linkend="model-pr">problem
report</link>.
</para>
<para>
- When code is written by the developer that is non-trivial, he
+ 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, he should
+ 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 <quote>pre-commit
test</quote>. When contributed code is received, it should be
@@ -1409,7 +1624,7 @@
set by the committer. After the number of days the
committer chose when setting the MFC have passed, an email
will automatically be
- sent to the committer reminding him to commit it to the -STABLE
+ 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.
</para>
@@ -1425,37 +1640,56 @@
<para>
<figure>
<title>Process summary: A committer commits code</title>
- <mediaobject><imageobject><imagedata fileref="proc-commit"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-commit"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to paragraph below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
When a committer has written a piece of code and
- wants to commit it, he first needs to determine if it is
+ 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, he should consult the maintainer before
+ 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 the deployed by
+ 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, he can choose to
+ a patch. If a vendor is affected, they can choose to
implement or ignore the patch.
</para>
<para>
<figure>
<title>Process summary: A contributor commits code</title>
- <mediaobject><imageobject><imagedata fileref="proc-contrib"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-contrib"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to paragraphs below and
+ above for a screen-reader friendly
+ version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
The difference when a contributor makes a code contribution is
- that he submits the code through the Bugzilla
+ that they submit the code through the Bugzilla
interface. This report is picked up by the maintainer who
reviews the code and commits it.
</para>
@@ -1548,13 +1782,22 @@
<para>
<figure>
<title>Process summary: Core elections</title>
- <mediaobject><imageobject><imagedata fileref="proc-elections"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-elections"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to paragraph below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
Core announces the election and selects an election
- manager. He prepares the elections, and when ready,
+ 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
@@ -1607,8 +1850,8 @@
requests by mail, Problem Reports, commercial funding for the development
of features, or contributions by the scientific community.
The wishes that come within the responsibility of a developer
- are given to that developer who prioritises his time between
- the request and his wishes. A common way to do this is maintain
+ 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
@@ -1629,7 +1872,7 @@
<para>
As the requests are prioritised by the individual developers on
- the basis of doing what they find interesting, necessary or are
+ 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
@@ -1707,10 +1950,55 @@
</para>
<para>
- <figure>
- <title>Jørgenssen's model for change integration</title>
- <mediaobject><imageobject><imagedata fileref="maintenance"/></imageobject></mediaobject>
- </figure>
+ Jørgenssen's model for change integration
+ <informaltable pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Stage</entry>
+ <entry>Next if successful</entry>
+ <entry>Next if unsuccessful</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>code</entry>
+ <entry>review</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>review</entry>
+ <entry>pre-commit test</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>pre-commit test</entry>
+ <entry>development release</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>development release</entry>
+ <entry>parallel debugging</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>parallel debugging</entry>
+ <entry>production release</entry>
+ <entry>code</entry>
+ </row>
+
+ <row>
+ <entry>production release</entry>
+ <entry></entry>
+ <entry>code</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</para>
<para>
@@ -1789,15 +2077,24 @@
<para>
<figure>
<title>Process summary: problem reporting</title>
- <mediaobject><imageobject><imagedata fileref="proc-pr"/></imageobject></mediaobject>
+ <mediaobject>
+ <imageobject><imagedata fileref="proc-pr"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to paragraph below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
A problem is reported by the report originator. It is
then classified by a bugbuster and handed to the correct
- maintainer. He verifies the problem and discusses the
- problem with the originator until he has enough
+ 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.
</para>
@@ -1833,7 +2130,7 @@
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 the committer's
+ actions will result in how long a suspension of the committer's
commit privileges.
<itemizedlist>
@@ -1861,7 +2158,7 @@
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
+ resort, due to its inherent tendency to create controversy.) All
suspensions are posted to the
<quote>developers</quote>
mailing list, a list available to committers only.
@@ -1912,10 +2209,10 @@
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
+ engineers' explicit consent. This feature- and code-freeze is
known as stabilising. During the release process, the release
engineer has the full authority to revert to older versions of
- code and thus "back out" changes should he find that the changes
+ code and thus "back out" changes should they find that the changes
are not suitable to be included in the release.
</para>
@@ -1962,7 +2259,7 @@
releases are considered release candidates. At the end of the
release process, a release is created with the new version
number, including binary distributions on web sites and the
- creation of a CD-ROM images. However, the release is not
+ creation of CD-ROM images. However, the release is not
considered "really released" until a <xref linkend="tool-pgp"/>-signed message stating
exactly that, is sent to the mailing list freebsd-announce; anything
labelled as a "release" before that may well be in-process and
@@ -2024,19 +2321,24 @@
<para>
- <figure>
- <title>Process summary: release engineering</title>
- <mediaobject><imageobject><imagedata fileref="proc-releng"/></imageobject></mediaobject>
- </figure>
+ <orderedlist>
+ <listitem><para>Make release schedule</para></listitem>
+ <listitem><para>Feature freeze</para></listitem>
+ <listitem><para>Code freeze</para></listitem>
+ <listitem><para>Make branch</para></listitem>
+ <listitem><para>Release candidate</para></listitem>
+ <listitem><para>Stabilize release (loop back to
+ previous step as many times as necessary; when
+ release is considered stable, proceed with next
+ step)
+ </para></listitem>
+ <listitem><para>Build packages</para></listitem>
+ <listitem><para>Warn mirrors</para></listitem>
+ <listitem><para>Publish release</para></listitem>
+ </orderedlist>
</para>
- <para>
- These are the stages in the release engineering
- process. Multiple release candidates may be created until
- the release is deemed stable enough to be released.
- </para>
-
<para>
<citation><xref linkend="freebsd-releng"/></citation>
</para>
@@ -2077,7 +2379,7 @@
and editing bug reports. The project uses its
web interface to send
<quote>Problem Reports</quote> to the
- projects central Bugzilla server. The committers also have web and
+ project's central Bugzilla server. The committers also have web and
command-line clients.
</para>
</section>
@@ -2088,7 +2390,7 @@
Mailman is a program that automates the
management of mailing lists. The FreeBSD Project uses it to run
16 general lists, 60 technical lists, 4 limited lists and 5 lists
- with CVS commit logs. It is
+ 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
@@ -2108,7 +2410,7 @@
using a public key architecture to allow people to digitally
sign and/or encrypt information in order to ensure secure
communication between two parties. A signature is used when
- sending information out many recipients, enabling them to verify
+ 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
@@ -2152,25 +2454,189 @@
<para>
A <quote>port</quote> is a set of meta-data and patches that
are needed to fetch, compile and install correctly an external piece of
- software on a FreeBSD system. The amount of ports have grown
+ software on a FreeBSD system. The amount of ports has grown
at a tremendous rate, as shown by the following figure.
</para>
<para>
<figure xml:id="fig-ports">
- <title>Number of ports added between 1996 and 2005</title>
- <mediaobject><imageobject><imagedata fileref="portsstatus"/></imageobject></mediaobject>
+ <title>Number of ports added between 1996 and 2008</title>
+ <mediaobject>
+ <imageobject><imagedata fileref="portsstatus"/></imageobject>
+ <textobject>
+ <literallayout class="monospaced"></literallayout>
+ </textobject>
+ <textobject>
+ <phrase>Refer to tables below for a
+ screen-reader friendly version.</phrase>
+ </textobject>
+ </mediaobject>
</figure>
</para>
<para>
- <xref linkend="fig-ports"/> is taken from
- <link xlink:href="https://www.freebsd.org/ports/growth/status.png">
- the FreeBSD web site</link>. It shows the number of ports
- available to FreeBSD in the period 1995 to 2005. It looks
- like the curve has first grown exponentionally, and then
- since the middle of 2001 grown linearly.
+ <xref linkend="fig-ports"/>
+ 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.
</para>
+ <para>
+ Approximate dates each multiple of 1000 ports is reached
+ <informaltable pgwide="1">
+ <tgroup cols="2">
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list