Date: Tue, 18 Jun 2013 21:59:05 +0000 (UTC) From: Glen Barber <gjb@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-projects@freebsd.org Subject: svn commit: r41948 - in projects/ISBN_1-57176-407-0: de_DE.ISO8859-1/htdocs/releases de_DE.ISO8859-1/share/xml en_US.ISO8859-1/articles/committers-guide en_US.ISO8859-1/articles/contributors en_US.... Message-ID: <201306182159.r5ILx56i029867@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gjb Date: Tue Jun 18 21:59:05 2013 New Revision: 41948 URL: http://svnweb.freebsd.org/changeset/doc/41948 Log: MFH: Merged /head/de_DE.ISO8859-1:r41735-41946 Merged /head/en_US.ISO8859-1:r41735-41781,41783-41938,41940-41946 Merged /head/fr_FR.ISO8859-1:r41735-41946 Merged /head/it_IT.ISO8859-15:r41735-41946 Merged /head/ja_JP.eucJP:r41735-41946 Merged /head/mn_MN.UTF-8:r41735-41946 Merged /head/nl_NL.ISO8859-1:r41735-41946 Merged /head/ru_RU.KOI8-R:r41735-41946 Merged /head/share:r41735-41946 Merged /head/zh_CN.GB2312:r41735-41946 Approved by: doceng (implicit) Added: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/announce.xml - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/announce.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/errata.html - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/errata.html projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/hardware.html - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/hardware.html projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/installation.html - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/installation.html projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/readme.html - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/readme.html projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/relnotes-detailed.html - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/relnotes-detailed.html projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/relnotes.xml - copied unchanged from r41938, head/en_US.ISO8859-1/htdocs/releases/8.4R/relnotes.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/releases/8.4R/ - copied from r41946, head/ja_JP.eucJP/htdocs/releases/8.4R/ projects/ISBN_1-57176-407-0/share/pgpkeys/alc.key - copied unchanged from r41946, head/share/pgpkeys/alc.key projects/ISBN_1-57176-407-0/share/pgpkeys/qingli.key - copied unchanged from r41946, head/share/pgpkeys/qingli.key projects/ISBN_1-57176-407-0/share/pgpkeys/vg.key - copied unchanged from r41946, head/share/pgpkeys/vg.key projects/ISBN_1-57176-407-0/share/security/advisories/FreeBSD-SA-13:06.mmap.asc - copied unchanged from r41946, head/share/security/advisories/FreeBSD-SA-13:06.mmap.asc projects/ISBN_1-57176-407-0/share/security/patches/SA-13:06/ - copied from r41946, head/share/security/patches/SA-13:06/ Modified: projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/share/xml/news.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/committers-guide/article.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.additional.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.committers.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/releng/article.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/basics/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/book.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/disks/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/geom/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/install/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/introduction/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/ports/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/preface/preface.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/vinum/chapter.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/porters-handbook/book.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/administration.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/cgi/man.cgi projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/layout/js/google.js projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/platforms/alpha.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/projects/c99/index.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/projects/cvsweb.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/Makefile projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/8.4R/schedule.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releases/index.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/releng/index.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/robots.txt projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/security/security.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/send-pr.xml projects/ISBN_1-57176-407-0/en_US.ISO8859-1/htdocs/where.xml projects/ISBN_1-57176-407-0/fr_FR.ISO8859-1/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/it_IT.ISO8859-15/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/Makefile projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/book.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/cutting-edge/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/desktop/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/install/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/introduction/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/mirrors/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/multimedia/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/books/handbook/ports/chapter.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/projects/Makefile projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/projects/cvsweb.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/security/security.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/send-pr.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/htdocs/where.xml projects/ISBN_1-57176-407-0/ja_JP.eucJP/share/xml/l10n.ent projects/ISBN_1-57176-407-0/ja_JP.eucJP/share/xml/news.xml projects/ISBN_1-57176-407-0/mn_MN.UTF-8/books/handbook/boot/chapter.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/Makefile projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/book.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/colophon.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/eresources/chapter.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/multimedia/chapter.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/books/handbook/preface/preface.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/htdocs/administration.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/htdocs/send-pr.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/htdocs/where.xml projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/share/xml/mailing-lists.ent projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/books/handbook/mail/Makefile projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/books/handbook/mail/chapter.xml projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/books/handbook/ports/Makefile projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/books/handbook/ports/chapter.xml projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/htdocs/releases/Makefile projects/ISBN_1-57176-407-0/share/images/articles/releng/branches-releng8.pic projects/ISBN_1-57176-407-0/share/misc/docbook.css projects/ISBN_1-57176-407-0/share/pgpkeys/hrs.key projects/ISBN_1-57176-407-0/share/pgpkeys/pgj.key projects/ISBN_1-57176-407-0/share/pgpkeys/pgpkeys-developers.xml projects/ISBN_1-57176-407-0/share/pgpkeys/pgpkeys.ent projects/ISBN_1-57176-407-0/share/pgpkeys/rm.key projects/ISBN_1-57176-407-0/share/xml/advisories.xml projects/ISBN_1-57176-407-0/share/xml/authors.ent projects/ISBN_1-57176-407-0/share/xml/developers.ent projects/ISBN_1-57176-407-0/share/xml/freebsd.ent projects/ISBN_1-57176-407-0/share/xml/man-refs.ent projects/ISBN_1-57176-407-0/share/xml/news.xml projects/ISBN_1-57176-407-0/share/xml/release.ent projects/ISBN_1-57176-407-0/share/xsl/freebsd-xhtml-common.xsl projects/ISBN_1-57176-407-0/zh_CN.GB2312/htdocs/releases/Makefile Directory Properties: projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/ (props changed) projects/ISBN_1-57176-407-0/en_US.ISO8859-1/ (props changed) projects/ISBN_1-57176-407-0/fr_FR.ISO8859-1/ (props changed) projects/ISBN_1-57176-407-0/it_IT.ISO8859-15/ (props changed) projects/ISBN_1-57176-407-0/ja_JP.eucJP/ (props changed) projects/ISBN_1-57176-407-0/mn_MN.UTF-8/ (props changed) projects/ISBN_1-57176-407-0/nl_NL.ISO8859-1/ (props changed) projects/ISBN_1-57176-407-0/ru_RU.KOI8-R/ (props changed) projects/ISBN_1-57176-407-0/share/ (props changed) projects/ISBN_1-57176-407-0/zh_CN.GB2312/ (props changed) Modified: projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/htdocs/releases/Makefile ============================================================================== --- projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/htdocs/releases/Makefile Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/htdocs/releases/Makefile Tue Jun 18 21:59:05 2013 (r41948) @@ -14,7 +14,7 @@ DOCS?= index.xml SUBDIR= 4.6.2R 4.7R 4.8R 4.9R 4.11R SUBDIR+= 5.0R 5.1R 5.2R 5.3R -.if defined $(NEW_BUILD) +.if defined(NEW_BUILD) SUBDIR= .endif Modified: projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/share/xml/news.xml ============================================================================== --- projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/share/xml/news.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/de_DE.ISO8859-1/share/xml/news.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -4,7 +4,7 @@ <!-- $FreeBSD$ $FreeBSDde$ - basiert auf: r41693 + basiert auf: r41837 --> <!-- Simple schema for FreeBSD Project news. @@ -39,9 +39,31 @@ <name>2013</name> <month> + <name>6</name> + + <day> + <name>4</name> + + <event> + <p>Erweiterte Commit-Privilegien: <a + href="mailto:gjb@FreeBSD.org">Glen Barber</a> (doc, ports, src)</p> + </event> + </day> + </month> + + <month> <name>5</name> <day> + <name>27</name> + + <event> + <p>Erweiterte Commit-Privilegien: <a + href="mailto:crees@FreeBSD.org">Chris Rees</a> (doc, ports)</p> + </event> + </day> + + <day> <name>14</name> <event> @@ -1281,7 +1303,7 @@ <event> <p>Neuer Committer: <a - href="mailto:rm@FreeBSD.org">Ruslan Mahmatkhanov</a> (ports)</p> + href="mailto:rm@FreeBSD.org">Ruslan Makhmatkhanov</a> (ports)</p> </event> </day> Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/committers-guide/article.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/committers-guide/article.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/committers-guide/article.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -604,19 +604,20 @@ <title>Daily Use</title> <para>This section will explain how to perform common day-to-day - operations with Subversion. There should be no difference - between <acronym>SVN</acronym> and <acronym>SVK</acronym> in - daily use, except for the revision renumbering mentioned - earlier.</para> + operations with Subversion.</para> <sect3> <title>Help</title> - <para>Both <acronym>SVN</acronym> and <acronym>SVK</acronym> - have built in help documentation. It can be accessed by + <para><acronym>SVN</acronym> + has built in help documentation. It can be accessed by typing the following command:</para> <screen>&prompt.user; <userinput>svn help</userinput></screen> + + <para>Additional information can be found in the <ulink + url="http://svnbook.red-bean.com/">; + Subversion Book</ulink>.</para> </sect3> <sect3> @@ -725,7 +726,7 @@ <title>Editing and Committing</title> <para>Unlike Perforce, - <acronym>SVN</acronym> and <acronym>SVK</acronym> do not + <acronym>SVN</acronym> does not need to be told in advance about file editing.</para> <para><command>svn commit</command> works like the equivalent Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.additional.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.additional.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.additional.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -7839,6 +7839,11 @@ </listitem> <listitem> + <para>Oleg Moskalenko + <email>mom040267@gmail.com</email></para> + </listitem> + + <listitem> <para>Oleg R. Muhutdinov <email>mor@whiteluna.com</email></para> </listitem> @@ -10573,11 +10578,6 @@ </listitem> <listitem> - <para>Veniamin Gvozdikov - <email>g.veniamin@googlemail.com</email></para> - </listitem> - - <listitem> <para>Vernon J. Schryver <email>vjs@mica.denver.sgi.com</email></para> </listitem> Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.committers.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.committers.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/contributors/contrib.committers.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -512,6 +512,10 @@ </listitem> <listitem> + <para>&a.vg;</para> + </listitem> + + <listitem> <para>&a.jhale;</para> </listitem> Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/releng/article.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/releng/article.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/articles/releng/article.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -47,7 +47,7 @@ <abstract> <para> <warning> - <para>2013/02/26: This document is outdated and does not + <para>2013/02/26: This document is partially outdated and does not accurately describe the current release procedures of the &os; Release Engineering team. The &os; Release Engineering team is currently reviewing this document and @@ -85,39 +85,38 @@ formal source code management provides. This has been a huge help in attracting more talented developers to &os;. However, I think everyone would agree that chaos would soon manifest if write - access was opened up to everyone on the Internet. Therefore only - a <quote>select</quote> group of nearly 300 people are given write - access to the Subversion repository. These + access to the main repository was opened up to everyone on the Internet. + Therefore only a <quote>select</quote> group of nearly 300 people are + given write access to the Subversion repository. These <ulink url="&url.articles.contributors;/article.html#staff-committers">committers</ulink> <footnote> <simpara> <ulink url="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</ulink> </simpara> </footnote> - are responsible for the bulk of &os; development. An elected + are usually the people who do the bulk of &os; development. An elected <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> <footnote> <simpara> <ulink url="&url.base;/administration.html#t-core">&os; Core Team</ulink> </simpara> </footnote> - of very senior developers provides some level of direction over - the project.</para> + of developers provide some level of direction over the project.</para> - <para>The rapid pace of <systemitem - class="osname">&os;</systemitem> development leaves little time - for polishing the development system into a production quality - release. To solve this dilemma, development continues on two - parallel tracks. The main development branch is the - <emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> of our Subversion - tree, known as <quote>&os;-CURRENT</quote> or + <para>The rapid pace of <systemitem class="osname">&os;</systemitem> + development makes the main development branch unsuitable for the + everyday use by the general public. In particular, stabilizing + efforts are required for polishing the development system into a + production quality release. To solve this conflict, development + continues on several parallel tracks. The main development branch + is the <emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> of + our Subversion tree, known as <quote>&os;-CURRENT</quote> or <quote>-CURRENT</quote> for short.</para> - <para>A more stable branch is maintained, known as + <para>A set of more stable branches are maintained, known as <quote>&os;-STABLE</quote> or <quote>-STABLE</quote> for short. - Both branches live in a master Subversion repository on a machine - maintained by the &os; Project. - &os;-CURRENT is the <quote>bleeding-edge</quote> of + All branches live in a master Subversion repository maintained by the + &os; Project. &os;-CURRENT is the <quote>bleeding-edge</quote> of &os; development where all new changes first enter the system. &os;-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and @@ -125,6 +124,17 @@ &os;-CURRENT and have been thoroughly tested by our user community.</para> + <para>The term <emphasis>stable</emphasis> in the name of the branch + refers to the presumed Application Binary Interface stability, + which is promised by the project. This means that a user + application compiled on an older version of the system from the + same branch works on a newer system from the same branch. The + ABI stability has improved greatly from the compared to previous + releases. In most cases, binaries from the older + <emphasis>STABLE</emphasis> systems run unmodified on newer systems, + including <emphasis>HEAD</emphasis>, assuming that the system + management interfaces are not used.</para> + <para>In the interim period between releases, monthly snapshots are built automatically by the &os; Project build machines and made available for download from <systemitem @@ -222,24 +232,34 @@ <para>New releases of &os; are released from the -STABLE branch at approximately four month intervals. The &os; release - process begins to ramp up 45 days before the anticipated release + process begins to ramp up 70-80 days before the anticipated release date when the release engineer sends an email to the development mailing lists to remind developers that they only have 15 days to integrate new changes before the code freeze. During this time, many developers perform what have become known as <quote>MFC - sweeps</quote>. <acronym>MFC</acronym> stands for <quote>Merge - From CURRENT</quote> and it describes the process of merging a - tested change from our -CURRENT development branch to our -STABLE - branch.</para> + sweeps</quote>.</para> + + <para><acronym>MFC</acronym> stands for <quote>Merge From + CURRENT</quote> and it describes the process of merging a tested + change from our -CURRENT development branch to our -STABLE branch. + Project policy requires any change to be first applied to + trunk, and merged to the -STABLE branches after sufficient + external testing was done by -CURRENT users (developers are + expected to extensively test the change before committing to + -CURRENT, but it is impossible for a person to exercise all usages + of the general-purpose operating system). Minimal MFC period is 3 + days, which is typically used only for trivial or critical + bugfixes.</para> <sect2> <title>Code Review</title> - <para>Thirty days before the anticipated release, the source - repository enters a <quote>code slush</quote>. During this + <para>Sixty days before the anticipated release, the source + repository enters a <quote>code freeze</quote>. During this time, all commits to the -STABLE branch must be approved by the - &a.re;. The kinds of changes that are allowed during this 15 day - period include:</para> + &a.re;, the approval process is technically enforced by the + pre-commit hook. The kinds of changes that are allowed during + this period include:</para> <itemizedlist> <listitem> @@ -260,30 +280,41 @@ </listitem> <listitem> + <para>Driver updates from the vendors.</para> + </listitem> + + <listitem> <para>Any additional change that the release engineering team feels is justified, given the potential risk.</para> </listitem> </itemizedlist> - <para>After the first 15 days of the code slush, a - <emphasis>release candidate</emphasis> is released for - widespread testing and the code enters a <quote>code - freeze</quote> where it becomes much harder to justify new - changes to the system unless a serious bug-fix or security issue - is involved. During the code freeze, at least one release - candidate is released per week, until the final release is - ready. During the days leading to the final release, the - release engineering team is in constant communication with the - security-officer team, the documentation maintainers, and the - port maintainers, to ensure that all of the + <para>Shortly after the code freeze is started, a + <emphasis>BETA1</emphasis> image is built and released for + widespread testing. During the code freeze, at least one beta + image or release candidate is released every two weeks until the + final release is ready. During the days preceeding the final + release, the release engineering team is in constant + communication with the security-officer team, the documentation + maintainers, and the port maintainers to ensure that all of the different components required for a successful release are available.</para> + + <para>After the quality of the BETA images is satisfying enough, + and no large and potentially risky changes are planned, the + release branch is created and <emphasis>Release + Candidate</emphasis> (RC) images are built from the release + branch, instead of the BETA images from the STABLE branch. + Also, the freeze on the STABLE branch is lifted and release + branch enters a <quote>hard code freeze</quote> where it becomes + much harder to justify new changes to the system unless a + serious bug-fix or security issue is involved.</para> </sect2> <sect2> <title>Final Release Checklist</title> - <para>When several release candidates have been made available for + <para>When several BETA images have been made available for widespread testing and all major issues have been resolved, the final release <quote>polishing</quote> can begin.</para> @@ -315,10 +346,10 @@ <screen>&prompt.root; <userinput>svn co $FSVN/releng/9.2 src</userinput></screen> <note> - <para>Creating <literal>releng</literal> branch and <literal>release</literal> - tags are restricted to - <ulink url="&url.base;/administration.html#t-subversion">Subversion administrators</ulink> - and the <ulink url="&url.base;/administration.html#t-re">Release Engineering Team</ulink>. + <para>Creating the <literal>releng</literal> branch and + <literal>release</literal> tags is done by the <ulink + url="&url.base;/administration.html#t-re">Release + Engineering Team</ulink>. </para> </note> Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -34,279 +34,261 @@ <chapter id="overview"> <title>Overview</title> - <para>Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that - documentation is produced. Your contributions are very + <para>Welcome to the &os; Documentation Project + (<acronym>FDP</acronym>). Quality documentation is very important + to the success of &os;. Your contributions are very valuable.</para> - <para>This document's main purpose is to clearly explain - <emphasis>how the FDP is organized</emphasis>, <emphasis>how to - write and submit documentation to the FDP</emphasis>, and - <emphasis>how to effectively use the tools available to you when - writing documentation</emphasis>.</para> - - <indexterm> - <primary>Membership</primary> - </indexterm> - <para>Everyone is welcome to join the FDP. There is no minimum - membership requirement, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - &a.doc;.</para> + <para>This document's main purpose is to explain how the + <acronym>FDP</acronym> is organized, how to write and submit + documentation, and how to effectively use the available + tools.</para> + + <para>Everyone is welcome to contribute to the + <acronym>FDP</acronym>. There is no membership requirement or + minimum quota of documentation that needs to be produced.</para> - <para>After you have finished reading this document you - should:</para> + <para>After you have finished reading this document you will be + able to:</para> <itemizedlist> <listitem> - <para>Know which documentation is maintained by the FDP.</para> + <para>Identify which parts of &os; are maintained by the + <acronym>FDP</acronym>.</para> </listitem> <listitem> - <para>Be able to read and understand the XML source code for - the documentation maintained by the FDP.</para> + <para>Install the required tools and files.</para> </listitem> <listitem> - <para>Be able to make changes to the documentation.</para> + <para>Make changes to the documentation.</para> </listitem> <listitem> - <para>Be able to submit your changes back for review and - eventual inclusion in the FreeBSD documentation.</para> + <para>Submit changes back for review and eventual inclusion in + the &os; documentation.</para> </listitem> </itemizedlist> <sect1 id="overview-doc"> - <title>The FreeBSD Documentation Set</title> + <title>The &os; Documentation Set</title> - <para>The FDP is responsible for four categories of FreeBSD - documentation.</para> + <para>The <acronym>FDP</acronym> is responsible for four + categories of &os; documentation.</para> - <variablelist> - <varlistentry> - <term>Manual pages</term> - - <listitem> - <para>The English language system manual pages are not - written by the FDP, as they are part of the base system. - However, the FDP can (and has) re-worded parts of existing - manual pages to make them clearer, or to correct - inaccuracies.</para> - - <para>The translation teams are responsible for translating - the system manual pages into different languages. These - translations are kept within the FDP.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FAQ</term> - - <listitem> - <para>The FAQ aims to address (in short question and answer - format) questions that are asked, or should be asked, on - the various mailing lists and newsgroups devoted to - FreeBSD. The format does not permit long and - comprehensive answers.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Handbook</term> - - <listitem> - <para>The Handbook aims to be the comprehensive on-line - resource and reference for FreeBSD users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Web site</term> - - <listitem> - <para>This is the main FreeBSD presence on the World Wide - Web, visible at <ulink - url="&url.base;/index.html">http://www.FreeBSD.org/</ulink>; - and many mirrors around the world. The web site is many - people's first exposure to FreeBSD.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The documentation for the web site, &os; Handbook, and FAQ - are available in the <literal>doc/</literal> Subversion - repository, which is located at - <literal>https://svn.FreeBSD.org/doc/</literal>.</para>; - - <para>Manual pages are available in the <literal>src/</literal> - Subversion repository, which is available at - <literal>https://svn.FreeBSD.org/base/</literal>.</para>; - - <para>This means that the logs of changes to these - files are visible to anyone, and anyone can use - <application>svn</application> to view the changes.</para> - - <para>In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the - Subversion repository as well (where the author has agreed to - this). In other cases the author has decided to keep his - documentation separate from the main FreeBSD repository. The - FDP endeavors to provide links to as much of this documentation - as possible.</para> - </sect1> + <itemizedlist> - <sect1 id="overview-before"> - <title>Before You Start</title> + <listitem> + <para><emphasis>Handbook</emphasis>: The Handbook is the + comprehensive online resource and reference for &os; + users.</para> + </listitem> - <para>This document assumes that you already know:</para> + <listitem> + <para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym> + uses a short question and answer format to address questions + that are frequently asked on the various mailing lists and + forums devoted to &os;. This format does not permit long + and comprehensive answers.</para> + </listitem> - <itemizedlist> <listitem> - <para>How to maintain an up-to-date local copy of the FreeBSD - documentation by maintaining a local copy of the FreeBSD - Subversion repository using - <application>svn</application>.</para> + <para><emphasis>Manual pages</emphasis>: The English language + system manual pages are usually not written by the + <acronym>FDP</acronym>, as they are part of the base system. + However, the <acronym>FDP</acronym> can reword parts of + existing manual pages to make them clearer or to correct + inaccuracies.</para> </listitem> <listitem> - <para>How to download and install new software using either - the FreeBSD Ports system or &man.pkg.add.1;.</para> + <para><emphasis>Web site</emphasis>: This is the main &os; + presence on the web, visible at <ulink + url="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</ulink>; + and many mirrors around the world. The web site is + typically a new user's first exposure to &os;.</para> </listitem> </itemizedlist> + + <para>Translation teams are responsible for translating + the Handbook and web site into different languages. Manual + pages are not translated.</para> + + <para>Documentation source for the &os; web site, Handbook, and + <acronym>FAQ</acronym> is available in the Subversion + repository at + <literal>https://svn.FreeBSD.org/doc/</literal>.</para>; + + <para>Source for manual pages is available in a separate + Subversion repository located at + <literal>https://svn.FreeBSD.org/base/</literal>.</para>; + + <para>The commit messages to the <acronym>FDP</acronym> + are visible to anyone usingv<application>svn</application>. + They are also archived at &a.svn-doc-all.url;.</para> + + <para>In addition, many people have written tutorials or how-to + articles about &os;. Some are stored in the + <acronym>FDP</acronym>. In other cases, the author has decided + to keep the documentation separate from the + <acronym>FDP</acronym>. The <acronym>FDP</acronym> endeavors to + provide links to as much of this documentation as + possible.</para> </sect1> <sect1 id="overview-quick-start"> <title>Quick Start</title> - <para>If you just want to get going, and feel confident you can - pick things up as you go along, follow these - instructions.</para> + <para>This section outlines the steps which new contributors need + to follow before they can make changes to the + <acronym>FDP</acronym>. New contributors will interact with + other members of the &os; Documentation Team which can assist in + learning how to use <acronym>XML</acronym> and the <xref + linkend="writing-style-guide"/>. If a new user contributes + regularly, a Documentation Team member may be assigned as a + mentor to guide the user through the process from contributor + to documentation committer.</para> <procedure> <step> - <para>Install the - <filename role="package">textproc/docproj</filename> - meta-port.</para> - - <screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput> -&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + <para>Subscribe to the &a.doc;. Some members of the mailing + list also interact on the <literal>#bsddocs</literal> + <acronym>IRC</acronym> channel on <ulink + url="http://www.efnet.org/">EFnet</ulink>.</para>; </step> <step> - <para>Get a local copy of the FreeBSD <filename>doc</filename> - tree using <application>svn</application>.</para> - - <para>If network bandwidth or local drive space is a concern, - then at minimum, the <filename>head/share</filename> and - <filename>head/<replaceable>language</replaceable>/share</filename> - directories will need to be checked out. For - example:</para> - - <screen>&prompt.user; <userinput>mkdir -p head/share</userinput> -&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput> -&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/share head/share</userinput> -&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen> - - <para>If you have plenty of disk space then you could check - out everything.</para> - - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head head</userinput></screen> - - <note> - <para><ulink - url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink>; - is a public <literal>SVN</literal> server. - Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> - </note> - </step> - - <step> - <para>If you are preparing a change to an existing book or - article, check it out of the repository as necessary. If - you are planning on contributing a new book or article then - use an existing one as a guide.</para> - - <para>For example, if you want to contribute a new article - about setting up a VPN between FreeBSD and Windows 2000 you - might do the following.</para> - - <procedure> - <step> - <para>Check out the <filename>articles</filename> - directory.</para> - - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/articles</userinput></screen>; - </step> - - <step> - <para>Copy an existing article to use as a template. In - this case, you have decided that your new article - belongs in a directory called - <filename>vpn-w2k</filename>.</para> - - <screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput> -&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen> - </step> - </procedure> - - <para>If you wanted to edit an existing document, such as the - FAQ, which is in - <filename>head/en_US.ISO8859-1/books/faq</filename> you - would check it out of the repository like this.</para> - - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>; - </step> - - <step> - <para>Edit the <filename>.xml</filename> files using your - editor of choice.</para> - </step> - - <step> - <para>Test the markup using the <maketarget>lint</maketarget> - target. This will quickly find any errors in the document - without actually performing the time-consuming - transformation.</para> - - <screen>&prompt.user; <userinput>make lint</userinput></screen> - - <para>When you are ready to actually build the document, you - may specify a single format or a list of formats in the - <varname>FORMATS</varname> variable. Currently, - <literal>html</literal>, <literal>html-split</literal>, - <literal>txt</literal>, <literal>ps</literal>, - <literal>pdf</literal>, and <literal>rtf</literal> are - supported. The most up to date list of supported formats is - listed at the top of the - <filename>head/share/mk/doc.docbook.mk</filename> file. - Make sure to use quotes around the list of formats when you - build more than one format with a single command.</para> - - <para>For example, to convert the document to - <literal>html</literal> only, you would use:</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen> - - <para>But when you want to convert the document to both - <literal>html</literal> and <literal>txt</literal> format, - you could use either two separate &man.make.1; runs, - with:</para> - - <screen>&prompt.user; <userinput>make FORMATS=html</userinput> -&prompt.user; <userinput>make FORMATS=txt</userinput></screen> - - <para>or, you can do it in one command:</para> - - <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen> + <para>Install the + <filename role="package">textproc/docproj</filename> + package or port. This meta-port installs all of the + utilities needed by the <acronym>FDP</acronym>.</para> </step> <step> - <para>Submit your changes using &man.send-pr.1;.</para> - </step> - </procedure> - </sect1> -</chapter> + <para>Install a local working copy of the documentation + from a mirror of the &os; repository. For the fastest + download, pick the nearest mirror from the list of <ulink + url="&url.books.handbook;/subversion-mirrors.html">Subversion + mirror sites</ulink>. If <filename + role="directory">/usr/doc</filename> already exists, move + or delete it first to prevent file conflicts.</para> + + <screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen> + </step> + + <step> + <para>Before making any documentation edits, configure your + editor to conform to <acronym>FDP</acronym> standards. + How to do so varies by editor. Some editor configurations + are listed in <xref linkend="writing-style"/>. The editor + should be configured as follows:</para> + <itemizedlist> + <listitem> + <para>Word wrap set to 70 characters.</para> + </listitem> + <listitem> + <para>Tab stops set to 2.</para> + </listitem> + <listitem> + <para>Replace each group of 8 leading spaces with a + single tab.</para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Determine which file to edit. Run + <command>svn up</command> within the local working copy + to make sure that it is current. Before making major + changes to a file, discuss the proposed changes first with + the &a.doc;.</para> + + <para>When making edits, determine which tags and entities + are needed to achieve the desired formatting. One way to + learn is to compare some text in the + <acronym>HTML</acronym> formatted version of the document + to the tags which surround the text or the entities that + represent that text in the <acronym>XML</acronym> file. + A reference to the commonly used tags and entities can be + found in <xref linkend="xml-markup"/>.</para> + </step> + + <step> + <para>Once the edits are complete, check for problems by + running:</para> + + <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para>While reviewing the output, edit the file to fix the + listed tab errors, spelling mistakes, and improper + grammar. Save the changes and rerun this command to find + any remaining problems. Repeat until all of the errors + that you deem fixable are resolved. If you get stuck + trying to fix errors, ask for assistance on the + &a.doc;.</para> + </step> + + <step> + <para><emphasis>Always</emphasis> build-test changes before + submitting them. By default, typing + <userinput>make</userinput> in the top-level directory of + the type of documentation being edited will generate that + documentation in split HTML format. For example, to build + the English version of the Handbook, type + <userinput>make</userinput> in the + <filename>en_US.ISO8859-1/books/handbook/</filename> + directory. This step is necessary to make sure that the + edits do not break the build.</para> + </step> + + <step> + <para>In order to build the output in other formats, other + <application>make</application> targets are defined in + <filename>head/share/mk/doc.docbook.mk</filename>. Use + quotes around the list of formats when building more than + one format with a single command.</para> + + <para>For example, to convert the document to both + <literal>.html</literal> and <literal>.txt</literal>, use + this command:</para> + + <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen> + + <para>Once these steps are successfully completed, generate a + <quote>diff file</quote> of the changes. While in <filename + class="directory">/usr/doc</filename>, run this command, + replacing <replaceable>bsdinstall</replaceable> with the + name of the directory containing the edits:</para> + + <screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> + </step> + + <step> + <para>Submit the diff file using the web-based <ulink + url="&url.base;/support.html#gnats">Problem + Report</ulink> system or with &man.send-pr.1;. If using + the web form, input a synopsis of <emphasis>[patch] + <replaceable>short description of + problem</replaceable></emphasis>. Select the category + <literal>docs</literal> and the class + <literal>doc-bug</literal>. The body of the message + should contain a short description of the edits and any + important discussion points. Use the + <guibutton>[ Browse... ]</guibutton> button to + attach the <literal>.diff.txt</literal> file and enter + the captcha phrase.</para> + + <para>It is important to remember that the + <acronym>FDP</acronym> is comprised of volunteers who + review edits in their spare time and who live in different + time zones across the globe. It takes time to review + edits and to either commit them or respond if additional + edits are required. If you do not receive a response in a + reasonable amount of time, send a follow-up email to the + &a.doc; and ask if anyone has had a chance to review the + patch or if additional information is required.</para> + </step> + </procedure> + </sect1> + </chapter> \ No newline at end of file Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml ============================================================================== --- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Tue Jun 18 21:57:41 2013 (r41947) +++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Tue Jun 18 21:59:05 2013 (r41948) @@ -205,13 +205,68 @@ also define them the first time they appear in each chapter.</para> - <para>The first three uses of an acronym should be enclosed in + <para>All acronyms should be enclosed in <sgmltag>acronym</sgmltag> tags, with a <literal>role</literal> attribute with the full term defined. This allows a link to the glossary to be created, and for mouseovers to be rendered with the fully expanded term.</para> </sect2> + <sect2 id="writing-style-beformal"> + <title>Be Formal</title> + + <para>Write in a formal style. Avoid addressing the reader + as <quote>you</quote>. For example, say + <quote>copy the file to <filename>/tmp</filename></quote> + rather than <quote>you can copy the file to + <filename>/tmp</filename></quote>.</para> + </sect2> + + <sect2 id="writing-style-confident"> + <title>Be Confident</title> + + <para>Avoid <emphasis>weasel words</emphasis> like + <quote>should</quote>, <quote>might</quote>, + <quote>try</quote>, or <quote>could</quote>. These words + imply that the speaker is unsure of the facts, and + create doubt in the reader.</para> + </sect2> + + <sect2 id="writing-style-imperative"> + <title>Be Imperative</title> + + <para>Give instructions as an imperative command: not + <quote>you should do this</quote>, but merely + <quote>do this</quote>.</para> + </sect2> + + <sect2 id="writing-style-simple"> + <title>Be Simple</title> + + <para>Avoid flowery or embellished speech, jokes, or colloquial + expressions. Write as simply and clearly as possible. Simple + text is easier to understand and makes the job of translation + easier.</para> + + <para>Keep explanations as short, simple, and clear as possible. + Avoid empty phrases like <quote>in order to</quote>, which + usually just means <quote>to</quote>. Avoid potentially + patronizing words like <quote>basically</quote>. Avoid Latin + terms like <quote>i.e.</quote> or <quote>cf.</quote>, which + may be unknown outside of academic or scientific + groups.</para> + </sect2> + + <sect2 id="writing-style-threecs"> + <title>Use the <quote>Three C</quote> Approach</title> + + <para>Writing must be <emphasis>clear</emphasis>, + <emphasis>complete</emphasis>, and + <emphasis>concise</emphasis>. These goals can conflict with + each other. Good writing consists of a balance between + them.</para> + </sect2> + <sect2> <title>Indentation</title> @@ -402,89 +457,80 @@ GB. Hardware compression …</lite <sect1 id="writing-style-word-list"> <title>Word List</title> - <para>The following is a small list of words spelled the way they - should be used in the FreeBSD Documentation Project. If the - word you are looking for is not in this list, then please - consult the <ulink - url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly - word list</ulink>.</para> - - <itemizedlist> - <listitem> - <para>2.2.X</para> - </listitem> - - <listitem> - <para>4.X-STABLE</para> - </listitem> - - <listitem> - <para>CD-ROM</para> - </listitem> - - <listitem> - <para>DoS <emphasis>(Denial of Service)</emphasis> </para> - </listitem> - - <listitem> - <para>Ports Collection</para> - </listitem> - - <listitem> - <para>IPsec</para> - </listitem> - - <listitem> - <para>Internet</para> - </listitem> - - <listitem> - <para>MHz</para> - </listitem> - - <listitem> - <para>Soft Updates</para> - </listitem> - - <listitem> - <para>Unix</para> - </listitem> - - <listitem> - <para>disk label</para> - </listitem> - - <listitem> - <para>email</para> - </listitem> - - <listitem> - <para>file system</para> - </listitem> - - <listitem> - <para>manual page</para> - </listitem> - - <listitem> - <para>mail server</para> - </listitem> - - <listitem> - <para>name server</para> - </listitem> - - <listitem> - <para>null-modem</para> - </listitem> - - <listitem> - <para>read-only</para> - </listitem> - - <listitem> - <para>web server</para> - </listitem> - </itemizedlist> + <para>This list of words shows the correct spelling and + capitalization when used in FreeBSD Documentation. If a word is + not on this list, ask about that word on the &a.doc;.</para> + + <informaltable frame="none" pgwide="0"> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306182159.r5ILx56i029867>