Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 31 May 2017 12:04:38 +0000 (UTC)
From:      Mathieu Arnold <mat@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r50299 - head/en_US.ISO8859-1/articles/committers-guide
Message-ID:  <201705311204.v4VC4cLl007100@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: mat
Date: Wed May 31 12:04:37 2017
New Revision: 50299
URL: https://svnweb.freebsd.org/changeset/doc/50299

Log:
  Pass the committer's guide through igor.
  
  Most of those were fixed.
  
  - "(s)" used 5 times Please do not form plurals this way. It is a
    holdover from lazy programming practices, is difficult to read, and
    almost always unnecessary. A plural formed with a plain "s" is usually
    correct when speaking about numbers of one or more.
  - "in order to" used 6 times Unless "in order to" has some special
    meaning here, "to" is simpler.
  - "i.e." used 1 time "I.e." (Latin "id est") means "that is" and is
    mostly used in academic and scientific writing. Consider replacing
    with the more common English words. Both forms are usually followed by
    a comma for a verbal pause: "i.e., a b c" or "that is, a b c"
  - "e.g." used 1 time "E.g." (Latin "exempli gratia") means "for example"
    and is mostly used in academic and scientific writing. Consider
    replacing with the more common English words. Both forms are usually
    followed by a comma for a verbal pause: "e.g., a b c" or "for example,
    a b c"
  - "simply" used 3 times Use "simply" to mean "in a simple manner",
    "just", or "merely", not the patronizing "details omitted because they
    are not simple enough for you". "basically" used 2 times Use
    "basically" to mean "essentially" or "fundamentally", not "only the
    basics are shown because anything more will be too complicated for
    you".
  - "the following" used 18 times "as follows" used 3 times If something
    is following, the reader can see it without being told.
  - "should" used 83 times Use "should" sparingly, it is feeble and
    suggests unsureness. Attempt to be imperative: "do this" rather than
    "you should do this".
  - "you" used 176 times "your" used 84 times "You" and "your" are
    informal and subjective. Attempt to be formal and objective: "the
    file" rather than "your file".
  
  Reviewed by:    wblock
  Sponsored by:   Absolight
  Differential Revision:  https://reviews.freebsd.org/D7531

Modified:
  head/en_US.ISO8859-1/articles/committers-guide/article.xml

Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.xml	Wed May 31 00:29:09 2017	(r50298)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.xml	Wed May 31 12:04:37 2017	(r50299)
@@ -312,7 +312,7 @@ You need a Passphrase to protect your secret key.</scr
 	</step>
       </procedure>
 
-      <para>Protect your private key and passphrase.  If either the
+      <para>Protect the private key and passphrase.  If either the
 	private key or passphrase may have been compromised or
 	disclosed, immediately notify
 	<email>accounts@FreeBSD.org</email> and revoke the key.</para>
@@ -361,12 +361,12 @@ You need a Passphrase to protect your secret key.</scr
     <screen>&prompt.user; <userinput>kpasswd</userinput></screen>
 
     <note>
-      <para>Unless you have used the Kerberos-authenticated services
-	of the &os;.org cluster previously,
+      <para>Unless the Kerberos-authenticated services
+	of the &os;.org cluster was used previously,
 	<errorname>Client unknown</errorname> will be shown.  This
 	error means that the
 	<command>ssh kpasswd.freebsd.org</command> method shown above
-	must be used first to initialize your Kerberos account.</para>
+	must be used first to initialize the Kerberos account.</para>
     </note>
 
   </sect1>
@@ -479,7 +479,7 @@ You need a Passphrase to protect your secret key.</scr
   <sect1 xml:id="subversion-primer">
     <title>Subversion Primer</title>
 
-    <para>It is assumed that you are already familiar with the basic
+    <para>New committers are assumed to already be familiar with the basic
       operation of Subversion.  If not, start by reading the
       <link xlink:href="http://svnbook.red-bean.com/">Subversion
 	Book</link>.</para>
@@ -558,11 +558,11 @@ You need a Passphrase to protect your secret key.</scr
 	  is the path to the repository, and <literal>head</literal>
 	  is the subdirectory within the repository.</para>
 
-	<para>If your &os; login name is different from your login
-	  name on your local machine, you must either include it in
+	<para>If your &os; login name is different from the login
+	  name used on the local machine, either include it in
 	  the <acronym>URL</acronym> (for example
 	  <literal>svn+ssh://jarjar@repo.freebsd.org/base/head</literal>),
-	  or add an entry to your <filename>~/.ssh/config</filename>
+	  or add an entry to <filename>~/.ssh/config</filename>
 	  in the form:</para>
 
 	<programlisting>Host repo.freebsd.org
@@ -754,7 +754,7 @@ You need a Passphrase to protect your secret key.</scr
 	<title>Help</title>
 
 	<para><acronym>SVN</acronym> has built in help documentation.
-	  It can be accessed by typing the following command:</para>
+	  It can be accessed by typing:</para>
 
 	<screen>&prompt.user; <userinput>svn help</userinput></screen>
 
@@ -832,8 +832,7 @@ You need a Passphrase to protect your secret key.</scr
 	<para>It is possible to anonymously check out the &os;
 	  repository with Subversion.  This will give access to a
 	  read-only tree that can be updated, but not committed back
-	  to the main repository.  To do this, use the following
-	  command:</para>
+	  to the main repository.  To do this, use:</para>
 
 	<screen>&prompt.user; <userinput>svn co https://svn.FreeBSD.org/base/head /usr/src</userinput></screen>
 
@@ -886,7 +885,7 @@ You need a Passphrase to protect your secret key.</scr
 	<screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>
 
 	<para>There is also a commit wrapper for the ports tree to
-	  handle the properties and sanity checking your
+	  handle the properties and sanity checking the
 	  changes:</para>
 
 	<screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit</userinput></screen>
@@ -1003,7 +1002,7 @@ You need a Passphrase to protect your secret key.</scr
 	<screen>&prompt.user; <userinput>svn diff -r179453:179454 ROADMAP.txt</userinput></screen>
 
 	<para>It can also show all changes for a specific changeset.
-	  The following will show what changes were made to the
+	  This command shows what changes were made to the
 	  current directory and all subdirectories in changeset
 	  179454:</para>
 
@@ -1026,8 +1025,7 @@ You need a Passphrase to protect your secret key.</scr
 	  conflict, Subversion will remember which files have
 	  conflicts and refuse to commit any changes to those files
 	  until explicitly told that the conflicts have been resolved.
-	  The simple, not yet deprecated procedure is the
-	  following:</para>
+	  The simple, not yet deprecated procedure is:</para>
 
 	<screen>&prompt.user; <userinput>svn resolved <replaceable>foo</replaceable></userinput></screen>
 
@@ -1123,7 +1121,7 @@ You need a Passphrase to protect your secret key.</scr
 	  <replaceable>~/freebsd</replaceable> with
 	  <filename>ROADMAP.txt</filename> and empty subdirectories,
 	  and nothing will happen when <command>svn update</command>
-	  is executed on the subdirectories.  However, the following
+	  is executed on the subdirectories.  However, this
 	  command will set the depth for
 	  <replaceable>head</replaceable> (in this case) to infinity,
 	  and fully populate it:</para>
@@ -1165,12 +1163,12 @@ You need a Passphrase to protect your secret key.</scr
 	  </listitem>
 	</itemizedlist>
 
-	<para>Branching is very fast.  The following command would be
+	<para>Branching is very fast.  This command would be
 	  used to branch <literal>RELENG_8</literal>:</para>
 
 	<screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8</userinput></screen>
 
-	<para>This is equivalent to the following set of commands
+	<para>This is equivalent to this set of commands
 	  which take minutes and hours as opposed to seconds,
 	  depending on your network connection:</para>
 
@@ -1215,7 +1213,7 @@ You need a Passphrase to protect your secret key.</scr
 	    Instead, mergeinfo is explicitly propagated down the tree.
 	    For merging something into
 	    <filename>branch/foo/bar/</filename>,
-	    the following rules apply:</para>
+	    these rules apply:</para>
 
 	  <orderedlist>
 	    <listitem>
@@ -1297,18 +1295,25 @@ You need a Passphrase to protect your secret key.</scr
 	    <literal>stable/10</literal> and Newer</title>
 
 	  <para>Starting with the <literal>stable/10</literal>
-	    branch, all merges should be
+	    branch, all merges are
 	    merged to and committed from the root of the
-	    branch.  All merges should look like:</para>
+	    branch.  All merges look like:</para>
 
 	  <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/head/ <replaceable>checkout</replaceable>
 &prompt.user; svn commit <replaceable>checkout</replaceable></screen>
 
-	  <para>Note that <replaceable>checkout</replaceable> should
-	    be a complete checkout of the branch to which the merge
+	  <para>Note that <replaceable>checkout</replaceable>
+	    must be a complete checkout of the branch to which the merge
 	    occurs.</para>
+
+	  <para>Merges to <literal>releng/</literal> branches must
+	    always originate from the corresponding
+	    <literal>stable/</literal> branch.  For example:</para>
+
+	  <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/stable/<replaceable>10</replaceable> releng/<replaceable>10.0</replaceable></screen>
 	</sect4>
 
+	<!-- FIXME: This probably needs to go away -->
 	<sect4 xml:id="oldmerge">
 	  <title>Selecting the Source and Target for
 	    <literal>stable/9</literal> and Older</title>
@@ -1319,8 +1324,8 @@ You need a Passphrase to protect your secret key.</scr
 	    a complete checkout.  This procedure proved extremely
 	    error-prone, with the convenience of partial checkouts for
 	    merges significantly outweighed by the complexity of
-	    picking mergeinfo targets.  The below describes this
-	    now-obsoleted procedure, which should be used
+	    picking mergeinfo targets.  The procedure below describes this
+	    now-obsoleted process, which should be used
 	    <emphasis>only for merges prior to
 	      <literal>stable/10</literal></emphasis>.</para>
 
@@ -1329,8 +1334,8 @@ You need a Passphrase to protect your secret key.</scr
 	    minimise property changes on unrelated directories.</para>
 
 	  <para>The rules for selecting the merge target (the
-	    directory that you will merge the changes to) can be
-	    summarized as follows:</para>
+	    directory where the changes are being merged to) can be
+	    summarized:</para>
 
 	  <orderedlist>
 	    <listitem>
@@ -1347,29 +1352,29 @@ You need a Passphrase to protect your secret key.</scr
 	    </listitem>
 
 	    <listitem>
-	      <para>Changes to kernel code should be merged to
+	      <para>Changes to kernel code are merged to
 		<filename>sys/</filename>.  For instance, a change to
-		the &man.ichwd.4; driver should be merged to
+		the &man.ichwd.4; driver is merged to
 		<filename>sys/</filename>, not
 		<filename>sys/dev/ichwd/</filename>.  Likewise, a
-		change to the TCP/IP stack should be merged to
+		change to the TCP/IP stack is merged to
 		<filename>sys/</filename>, not
 		<filename>sys/netinet/</filename>.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes to code under <filename>etc/</filename>
-		should be merged at <filename>etc/</filename>, not
+		is merged at <filename>etc/</filename>, not
 		below it.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes to vendor code (code in
 		<filename>contrib/</filename>,
-		<filename>crypto/</filename> and so on) should be
+		<filename>crypto/</filename> and so on) are
 		merged to the directory where vendor imports happen.
 		For instance, a change to
-		<filename>crypto/openssl/util/</filename> should be
+		<filename>crypto/openssl/util/</filename> is
 		merged to <filename>crypto/openssl/</filename>.  This
 		is rarely an issue, however, since changes to vendor
 		code are usually merged wholesale.</para>
@@ -1379,8 +1384,8 @@ You need a Passphrase to protect your secret key.</scr
 	      <para>Changes to userland programs should as a general
 		rule be merged to the directory that contains the
 		Makefile for that program.  For instance, a change to
-		<filename>usr.bin/xlint/arch/i386/</filename> should
-		be merged to
+		<filename>usr.bin/xlint/arch/i386/</filename>
+		is merged to
 		<filename>usr.bin/xlint/</filename>.</para>
 	    </listitem>
 
@@ -1403,7 +1408,7 @@ You need a Passphrase to protect your secret key.</scr
 	    </listitem>
 
 	    <listitem>
-	      <para>Changes to manual pages should be merged to
+	      <para>Changes to manual pages are merged to
 		<filename>share/man/man<replaceable>N</replaceable>/</filename>,
 		for the appropriate value of
 		<literal>N</literal>.</para>
@@ -1411,14 +1416,14 @@ You need a Passphrase to protect your secret key.</scr
 
 	    <listitem>
 	      <para>Other changes to <filename>share/</filename>
-		should be merged to the appropriate subdirectory and
+		are merged to the appropriate subdirectory and
 		not to <filename>share/</filename> directly.</para>
 	    </listitem>
 
 	    <listitem>
 	      <para>Changes to a top-level file in the source tree
 		such as <filename>UPDATING</filename> or
-		<filename>Makefile.inc1</filename> should be merged
+		<filename>Makefile.inc1</filename> are merged
 		directly to that file rather than to the root of the
 		whole tree.  Yes, this is an exception to the first
 		three rules.</para>
@@ -1429,19 +1434,19 @@ You need a Passphrase to protect your secret key.</scr
 	    </listitem>
 	  </orderedlist>
 
-	  <para>If you need to merge changes to several places at once
+	  <para>If a merge changes several places at once
 	    (for instance, changing a kernel interface and every
 	    userland program that uses it), merge each target
 	    separately, then commit them together.  For instance, if
-	    you merge a revision that changed a kernel
+	    merging a revision that changed a kernel
 	    <acronym>API</acronym> and updated all the userland bits
-	    that used that <acronym>API</acronym>, you would merge the
+	    that used that <acronym>API</acronym>, merge the
 	    kernel change to sys, and the userland bits to the
 	    appropriate userland directories, then commit all of these
 	    in one go.</para>
 
 	  <para>The source will almost invariably be the same as the
-	    target.  For instance, you will always merge
+	    target.  For instance, always merge
 	    <filename>stable/7/lib/libc/</filename> from
 	    <filename>head/lib/libc/</filename>.  The only exception
 	    would be when merging changes to code that has moved in
@@ -1455,10 +1460,10 @@ You need a Passphrase to protect your secret key.</scr
 	  <title>Preparing the Merge Target</title>
 
 	  <para>Because of the mergeinfo propagation issues described
-	    earlier, it is very important that you never merge changes
-	    into a sparse working copy.  You must always have a full
-	    checkout of the branch you will merge into.  For instance,
-	    when merging from HEAD to 7, you must have a full checkout
+	    earlier, it is very important to never merge changes
+	    into a sparse working copy.  Always use a full
+	    checkout of the branch being merge into.  For instance,
+	    when merging from HEAD to 7, use a full checkout
 	    of stable/7:</para>
 
 	  <screen>&prompt.user; <userinput>cd stable/7</userinput>
@@ -1490,7 +1495,7 @@ You need a Passphrase to protect your secret key.</scr
 	  <sect5>
 	    <title>The Principles</title>
 
-	    <para>Say you would like to merge:</para>
+	    <para>For example, To merge:</para>
 
 	    <itemizedlist>
 	      <listitem>
@@ -1542,7 +1547,7 @@ $target - head/$source:$P,$Q,$R</screen>
 	  <sect5>
 	    <title>Practical Example</title>
 
-	    <para>As a practical example, consider the following
+	    <para>As a practical example, consider this
 	      scenario.  The changes to <filename>netmap.4</filename>
 	      in r238987 are to be merged from CURRENT to 9-STABLE.
 	      The file resides in
@@ -1645,7 +1650,7 @@ U    stable/9/share/man/man4/netmap.4
 	      <para>Vendor patches: these are patches that have been
 		issued by the vendor, or that have been extracted from
 		the vendor's version control system, which address
-		issues which in your opinion cannot wait until the
+		issues which cannot wait until the
 		next vendor release.</para>
 	    </listitem>
 
@@ -1660,7 +1665,7 @@ U    stable/9/share/man/man4/netmap.4
 
 	  <itemizedlist>
 	    <listitem>
-	      <para>Vendor patches should be committed to the vendor
+	      <para>Vendor patches must be committed to the vendor
 		branch, and merged from there to head.  If the patch
 		addresses an issue in a new release that is currently
 		being imported, it <emphasis>must not</emphasis> be
@@ -1671,7 +1676,7 @@ U    stable/9/share/man/man4/netmap.4
 	    </listitem>
 
 	    <listitem>
-	      <para>&os; patches should be committed directly to
+	      <para>&os; patches are committed directly to
 		head.</para>
 	    </listitem>
 	  </itemizedlist>
@@ -1793,7 +1798,7 @@ U    stable/9/share/man/man4/netmap.4
 	    <para>Now, the sources must be copied into
 	      <filename><replaceable>dist</replaceable></filename> and
 	      the <command>svn add</command> and
-	      <command>svn rm</command> commands should be used as
+	      <command>svn rm</command> commands are used as
 	      needed:</para>
 
 	    <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
@@ -1817,8 +1822,8 @@ U    stable/9/share/man/man4/netmap.4
 	      <literal>*</literal>.  No other properties should exist
 	      on any file in the tree.</para>
 
-	    <para>Committing is now possible, however it is good
-	      practice to make sure that everything is OK by using the
+	    <para>Committing is now possible.  However, it is good
+	      practice to make sure that everything is okay by using the
 	      <command>svn stat</command> and
 	      <command>svn diff</command> commands.</para>
 	  </sect5>
@@ -1826,7 +1831,7 @@ U    stable/9/share/man/man4/netmap.4
 	  <sect5>
 	    <title>Tagging</title>
 
-	    <para>Once committed, vendor releases should be tagged for
+	    <para>Once committed, vendor releases are tagged for
 	      future reference.  The best and quickest way to do this
 	      is directly in the repository:</para>
 
@@ -1856,8 +1861,8 @@ U    stable/9/share/man/man4/netmap.4
 &prompt.user; <userinput>svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
 
 	  <para>The <literal>--accept=postpone</literal> tells
-	    Subversion that it should not complain because merge
-	    conflicts will be taken care of manually.</para>
+	    Subversion not to complain about merge
+	    conflicts as they will be handled manually.</para>
 
 	  <tip xml:id="svn-advanced-use-vendor-imports-pre-svn">
 	    <para>The <command>cvs2svn</command> changeover occurred
@@ -1901,9 +1906,9 @@ U    stable/9/share/man/man4/netmap.4
 
 	  <para>The <literal>--no-diff-deleted</literal> tells
 	    Subversion not to complain about files that are in the
-	    vendor tree but not in the main tree, i.e., things that
+	    vendor tree but not in the main tree.  Things that
 	    would have previously been removed before the vendor
-	    import, like for example the vendor's makefiles
+	    import, like the vendor's makefiles
 	    and configure scripts.</para>
 
 	  <para>Using <acronym>CVS</acronym>, once a file was off the
@@ -1992,8 +1997,8 @@ U    stable/9/share/man/man4/netmap.4
 
 	<note>
 	  <para>It is important to ensure that the mergeinfo
-	    is correct when reverting a file in order to permit
-	    <command>svn mergeinfo --show-revs=eligible</command> to work as
+	    is correct when reverting a file to permit
+	    <command>svn mergeinfo --eligible</command> to work as
 	    expected.</para>
 	</note>
 
@@ -2044,18 +2049,19 @@ U    stable/9/share/man/man4/netmap.4
 	<title>Setting up a <application>svnsync</application>
 	  Mirror</title>
 
-	<para>You probably do not want to do this unless there is a
-	  good reason for it.  Such reasons might be to support many
-	  multiple local read-only client machines, or if your network
+	<para>Avoid setting up a <application>svnsync</application>
+	  mirror unless there is a very good reason for it.  Such
+	  reasons might be to support
+	  multiple local read-only client machines, or if the network
 	  bandwidth is limited.  Starting a fresh mirror from empty
 	  would take a very long time.  Expect a minimum of 10 hours
-	  for high speed connectivity.  If you have international
-	  links, expect this to take 4 to 10 times longer.</para>
+	  for high speed connectivity.  If international links are
+	  involved, expect this to take four to ten times longer.</para>
 
 	<para>A far better option is to grab a seed file.  It is large
 	  (~1GB) but will consume less network traffic and take less
-	  time to fetch than a svnsync will.  This is possible in one
-	  of the following three ways:</para>
+	  time to fetch than a svnsync will.  There are several ways
+	  to do this:</para>
 
 	<screen>&prompt.user; <userinput>rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .</userinput></screen>
 
@@ -2063,15 +2069,15 @@ U    stable/9/share/man/man4/netmap.4
 
 	<screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen>;
 
-	<para>Once you have the file, extract it to somewhere like
+	<para>Extract the file to somewhere like
 	  <filename>home/svnmirror/base/</filename>.
 	  Then, update it, so that it fetches changes since the last
 	  revision in the archive:</para>
 
 	<screen>&prompt.user; <userinput>svnsync sync file:///home/svnmirror/base</userinput></screen>
 
-	<para>You can then set that up to run from &man.cron.8;, do
-	  checkouts locally, set up a svnserve server for your local
+	<para>Now, set that up to run from &man.cron.8;, do
+	  checkouts locally, set up a svnserve server for local
 	  machines to talk to, etc.</para>
 
 	<para>The seed mirror is set to fetch from
@@ -2114,18 +2120,18 @@ U    stable/9/share/man/man4/netmap.4
 	  while and is finally committed back to the original branch.
 	  During development code migration in one direction (from
 	  head to the branch only).  No code is committed back to head
-	  until the end.  Once you commit back at the end, the branch
-	  is dead (although you can have a new branch with the same
-	  name after you delete the branch if you want).</para>
+	  until the end.  Once the branch is commited back at the end,
+	  it is dead (although a new branch with the same name can be
+	  created after the dead one was deleted).</para>
 
 	<para>As per <link
 	    xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</link>,
 	  work that is intended to be merged back into HEAD should be
-	  in <filename>base/projects/</filename>.  If you are doing
-	  work that is beneficial to the &os; community in some way
+	  in <filename>base/projects/</filename>.  If the
+	  work is beneficial to the &os; community in some way
 	  but not intended to be merged directly back into HEAD then
 	  the proper location is
-	  <filename>base/user/<replaceable>your-name</replaceable>/</filename>.
+	  <filename>base/user/<replaceable>username</replaceable>/</filename>.
 	  <link
 	    xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
 	    page</link> contains further details.</para>
@@ -2155,10 +2161,10 @@ U    stable/9/share/man/man4/netmap.4
     <sect2>
       <title>Some Tips</title>
 
-      <para>In commit logs etc., <quote>rev 179872</quote> should be
+      <para>In commit logs etc., <quote>rev 179872</quote> is
 	spelled <quote>r179872</quote> as per convention.</para>
 
-      <para>Speeding up svn is possible by adding the following to
+      <para>Speeding up svn is possible by adding these entries to
 	<filename>~/.ssh/config</filename>:</para>
 
       <screen>Host *
@@ -2236,7 +2242,7 @@ freebsd-mfc-after = 2 weeks</programlisting>
 	</listitem>
 
 	<listitem>
-	  <para>All <filename>src</filename> commits should go to
+	  <para>All <filename>src</filename> commits go to
 	    &os.current; first before being merged to &os.stable;.
 	    The &os.stable; branch must maintain
 	    <acronym>ABI</acronym> and <acronym>API</acronym>
@@ -2421,20 +2427,19 @@ freebsd-mfc-after = 2 weeks</programlisting>
 	    taken up permanent residence on
 	    <systemitem>freefall</systemitem> may get truncated
 	    without warning if space needs to be freed, so forward it
-	    or read it and you will not lose it.</para>
+	    or save it elsewhere.</para>
 
 	  <para>Due to the severe load dealing with SPAM places on the
-	    central mail servers that do the mailing list processing
+	    central mail servers that do the mailing list processing,
 	    the front-end server does do some basic checks and will
 	    drop some messages based on these checks.  At the moment
 	    proper DNS information for the connecting host is the only
 	    check in place but that may change.  Some people blame
-	    these checks for bouncing valid email.  If you want these
-	    checks turned off for your email you can place a file
-	    named <filename>.spam_lover</filename> in your home
-	    directory on <systemitem
-	      class="fqdomainname">freefall.FreeBSD.org</systemitem>
-	    to disable the checks for your email.</para>
+	    these checks for bouncing valid email.  To have these
+	    checks turned off for your email, create a file
+	    named <filename>~/.spam_lover</filename>
+	    on <systemitem
+	      class="fqdomainname">freefall.FreeBSD.org</systemitem>.</para>
 	</step>
       </procedure>
 
@@ -2498,8 +2503,7 @@ freebsd-mfc-after = 2 weeks</programlisting>
       how commit logs are formatted.</para>
 
     <para>As well as including an informative message with each
-      commit you may need to include some additional
-      information.</para>
+      commit, some additional information may be needed.</para>
 
     <para>This information consists of one or more lines
       containing the key word or phrase, a colon, tabs for formatting,
@@ -2526,7 +2530,7 @@ freebsd-mfc-after = 2 weeks</programlisting>
 		username on the &os; cluster.</para>
 
 	      <para>If the submitter is the maintainer of the port
-		to which you are committing, include "(maintainer)"
+		being committed, include "(maintainer)"
 		after the email address.</para>
 
 	      <para>Avoid obfuscating the email address of the
@@ -2627,9 +2631,9 @@ freebsd-mfc-after = 2 weeks</programlisting>
     <example>
       <title>Commit Log for a Commit Based on a PR</title>
 
-      <para>You want to commit a change based on a PR submitted by
-	John Smith containing a patch.  The end of the commit message
-	should look something like this.</para>
+      <para>The commit is based on a patch from a PR submitted by John
+	Smith.  The commit message <quote>PR</quote> and
+	<quote>Submitted by</quote> fields are filled..</para>
 
       <programlisting>...
 
@@ -2640,8 +2644,8 @@ freebsd-mfc-after = 2 weeks</programlisting>
     <example>
       <title>Commit Log for a Commit Needing Review</title>
 
-      <para>You want to change the virtual memory system.  You have
-	posted patches to the appropriate mailing list (in this
+      <para>The virtual memory system is being changed.  After
+	posting patches to the appropriate mailing list (in this
 	case, <literal>freebsd-arch</literal>) and the changes have
 	been approved.</para>
 
@@ -2653,8 +2657,8 @@ freebsd-mfc-after = 2 weeks</programlisting>
     <example>
       <title>Commit Log for a Commit Needing Approval</title>
 
-      <para>You want to commit a port.  You have collaborated with
-	the listed MAINTAINER, who has told you to go ahead and
+      <para>Commit a port, after working with
+	the listed MAINTAINER, who said to go ahead and
 	commit.</para>
 
       <programlisting>...
@@ -2669,7 +2673,7 @@ freebsd-mfc-after = 2 weeks</programlisting>
       <title>Commit Log for a Commit Bringing in Code from
 	OpenBSD</title>
 
-      <para>You want to commit some code based on work done in the
+      <para>Commiting some code based on work done in the
 	OpenBSD project.</para>
 
       <programlisting>...
@@ -2681,7 +2685,7 @@ freebsd-mfc-after = 2 weeks</programlisting>
       <title>Commit Log for a Change to &os.current; with a Planned
 	Commit to &os.stable; to Follow at a Later Date.</title>
 
-      <para>You want to commit some code which will be merged from
+      <para>Committing some code which will be merged from
 	&os.current; into the &os.stable; branch after two
 	weeks.</para>
 
@@ -2697,15 +2701,15 @@ MFC after:      <replaceable>2 weeks</replaceable></pr
 	<literal>month</literal>, <literal>months</literal>.</para>
     </example>
 
-    <para>In many cases you may need to combine some of these.</para>
+    <para>It is often necessary to combine these.</para>
 
     <para>Consider the situation where a user has submitted a PR
-      containing code from the NetBSD project.  You are looking at the
-      PR, but it is not an area of the tree you normally work in, so
-      you have decided to get the change reviewed by the
+      containing code from the NetBSD project.  Looking at the PR, the
+      developer sees it is not an area of the tree they normally work
+      in, so they have the change reviewed by the
       <literal>arch</literal> mailing list.  Since the change is
-      complex, you opt to <acronym>MFC</acronym> after one month to
-      allow adequate testing.</para>
+      complex, the developer opts to <acronym>MFC</acronym> after one
+      month to allow adequate testing.</para>
 
     <para>The extra information to include in the commit would look
       something like</para>
@@ -2725,7 +2729,7 @@ Relnotes:           yes</programlisting>
   <sect1 xml:id="pref-license">
     <title>Preferred License for New Files</title>
 
-    <para>Currently the &os; Project suggests and uses the following
+    <para>The &os; Project suggests and uses this
       text as the preferred license scheme:</para>
 
     <programlisting>/*-
@@ -2854,27 +2858,27 @@ Relnotes:           yes</programlisting>
   <sect1 xml:id="developer.relations">
     <title>Developer Relations</title>
 
-    <para>If you are working directly on your own code or on code
+    <para>When working directly on your own code or on code
       which is already well established as your responsibility, then
       there is probably little need to check with other committers
-      before jumping in with a commit.  If you see a bug in an area of
+      before jumping in with a commit.  Working on a bug in an area of
       the system which is clearly orphaned (and there are a few such
-      areas, to our shame), the same applies.  If, however, you are
-      about to modify something which is clearly being actively
+      areas, to our shame), the same applies.  Trying
+      to modify something which is clearly being actively
       maintained by someone else (and it is only by watching the
       <literal><replaceable>repository</replaceable>-committers</literal>
-      mailing list that you can really get a feel for just what is and
+      mailing list that a developer can really get a feel for just what is and
       is not) then consider sending the change to them instead, just
-      as you would have before becoming a committer.  For ports, you
-      should contact the listed <varname>MAINTAINER</varname> in the
+      as a developer would have before becoming a committer.  For ports,
+      contact the listed <varname>MAINTAINER</varname> in the
       <filename>Makefile</filename>.  For other parts of the
-      repository, if you are unsure who the active maintainer might
-      be, it may help to scan the revision history to see who has
+      repository, if it s not clear who the active maintainer
+      is, it may help to scan the revision history to see who has
       committed changes in the past.  An example script that lists
       each person who has committed to
       a given file along with the number of commits each person has
       made can be found at on <systemitem>freefall</systemitem> at
-      <filename>~eadler/bin/whodid</filename>.  If your queries go
+      <filename>~eadler/bin/whodid</filename>.  If queries go
       unanswered or the committer otherwise indicates a lack of
       interest in the area affected, go ahead and commit it.</para>
 
@@ -2884,20 +2888,20 @@ Relnotes:           yes</programlisting>
 	output.</para>
     </note>
 
-    <para>If you are unsure about a commit for any reason at all, have
+    <para>If there is any doubt about a commit for any reason at all, have
       it reviewed by <literal>-hackers</literal> before committing.
       Better to have it flamed then and there rather than when it is
-      part of the repository.  If you do happen to commit something
-      which results in controversy erupting, you may also wish to
+      part of the repository.  If a commit does
+      results in controversy erupting, it may be advisable to
       consider backing the change out again until the matter is
-      settled.  Remember &ndash; with a version control system we can
+      settled.  Remember, with a version control system we can
       always change it back.</para>
 
-    <para>Do not impugn the intentions of someone you disagree with.
-      If they see a different solution to a problem than you, or even
-      a different problem, it is not because they are stupid, because
+    <para>Do not impugn the intentions of others.
+      If they see a different solution to a problem, or even
+      a different problem, it is probably not because they are stupid, because
       they have questionable parentage, or because they are trying to
-      destroy your hard work, personal image, or &os;, but simply
+      destroy hard work, personal image, or &os;, but basically
       because they have a different outlook on the world.  Different
       is good.</para>
 
@@ -2921,7 +2925,7 @@ Relnotes:           yes</programlisting>
   <sect1 xml:id="if-in-doubt">
     <title>If in Doubt...</title>
 
-    <para>When you are not sure about something, whether it be a
+    <para>When unsure about something, whether it be a
       technical issue or a project convention be sure to ask.  If you
       stay silent you will never make progress.</para>
 
@@ -2930,7 +2934,7 @@ Relnotes:           yes</programlisting>
       person that knows the answer.  This way everyone will be able to
       learn from the question and the answer.</para>
 
-    <para>For project specific or administrative questions you should
+    <para>For project specific or administrative questions
       ask, in order:</para>
 
     <itemizedlist>
@@ -2943,7 +2947,7 @@ Relnotes:           yes</programlisting>
       </listitem>
 
       <listitem>
-	<para>Any team with a "hat", as they should give you a
+	<para>Any team with a "hat", as they can give you a
 	  definitive answer.</para>
       </listitem>
 
@@ -3096,8 +3100,8 @@ Relnotes:           yes</programlisting>
 	  <para>&a.svn-src-all.name;, &a.svn-ports-all.name; and
 	    &a.svn-doc-all.name; are the mailing lists that the
 	    version control system uses to send commit messages to.
-	    You should <emphasis>never</emphasis> send email directly
-	    to these lists.  You should only send replies to this list
+	    <emphasis>Never</emphasis> send email directly
+	    to these lists.  Only send replies to this list
 	    when they are short and are directly related to a
 	    commit.</para>
 	</listitem>
@@ -3113,7 +3117,7 @@ Relnotes:           yes</programlisting>
 	    voting, announcements, etc.</para>
 
 	  <para>The &a.developers; is for the exclusive use of &os;
-	    committers.  In order to develop &os;, committers must
+	    committers.  To develop &os;, committers must
 	    have the ability to openly discuss matters that will be
 	    resolved before they are publicly announced.  Frank
 	    discussions of work in progress are not suitable for open
@@ -3187,14 +3191,13 @@ Relnotes:           yes</programlisting>
       </step>
     </procedure>
 
-    <para>Now you should be able to use &man.ssh-add.1; for
-      authentication once per session.  This will prompt you for
-      your private key's pass phrase, and then store it in your
-      authentication agent (&man.ssh-agent.1;).  If you no longer
-      wish to have your key stored in the agent, issuing
-      <command>ssh-add -d</command> will remove it.</para>
+    <para>Now &man.ssh-add.1; can be used for
+      authentication once per session.  It prompts for
+      the private key's pass phrase, and then stores it in the
+      authentication agent (&man.ssh-agent.1;).  Use <command>ssh-add
+	-d</command> to remove keys stored in the agent.<para>
 
-    <para>Test by doing something such as <command>ssh
+    <para>Test with a simple remote command: <command>ssh
 	freefall.FreeBSD.org ls /usr</command>.</para>
 
     <para>For more information, see
@@ -3312,7 +3315,7 @@ Relnotes:           yes</programlisting>
 	  <filename>src/crypto</filename>, or
 	  <filename>src/sys/contrib</filename> trees without
 	  <emphasis>explicit</emphasis> approval from the respective
-	  maintainer(s).</para>
+	  maintainers.</para>
       </listitem>
     </orderedlist>
 
@@ -3382,7 +3385,7 @@ Relnotes:           yes</programlisting>
 	    are angry or otherwise behave in a manner which is likely
 	    to strike others as needlessly confrontational.  First
 	    calm down, then think about how to communicate in the most
-	    effective fashion for convincing the other person(s) that
+	    effective fashion for convincing the other persons that
 	    your side of the argument is correct, do not just blow off
 	    some steam so you can feel better in the short term at the
 	    cost of a long-term flame war.  Not only is this very bad
@@ -3427,21 +3430,21 @@ Relnotes:           yes</programlisting>
 	  <para>Discuss any significant change
 	    <emphasis>before</emphasis> committing.</para>
 
-	  <para>The repository is not where changes should be
+	  <para>The repository is not where changes are
 	    initially submitted for correctness or argued over, that
-	    should happen first in the mailing lists or by use of the
-	    Phabricator service and the commit should only happen once
+	    happens first in the mailing lists or by use of the
+	    Phabricator service.  The commit will only happen once
 	    something resembling consensus has been reached.  This
-	    does not mean that you have to ask permission before
+	    does not mean that permission is required before
 	    correcting every obvious syntax error or manual page
-	    misspelling, simply that you should try to develop a feel
+	    misspelling, just that it is good to develop a feel
 	    for when a proposed change is not quite such a no-brainer
 	    and requires some feedback first.  People really do not
 	    mind sweeping changes if the result is something clearly
 	    better than what they had before, they just do not like
 	    being <emphasis>surprised</emphasis> by those changes.
-	    The very best way of making sure that you are on the right
-	    track is to have your code reviewed by one or more other
+	    The very best way of making sure that things are on the right
+	    track is to have code reviewed by one or more other
 	    committers.</para>
 
 	  <para>When in doubt, ask for review!</para>
@@ -3464,7 +3467,7 @@ Relnotes:           yes</programlisting>
 	    maintainer need to be reviewed by at least one other
 	    maintainer.  In cases where the
 	    <quote>maintainer-ship</quote> of something is not clear,
-	    you can also look at the repository logs for the file(s)
+	    look at the repository logs for the files
 	    in question and see if someone has been working recently
 	    or predominantly in that area.</para>
 
@@ -3546,15 +3549,15 @@ Relnotes:           yes</programlisting>
 	    self-control, tempers are lost and angry words are
 	    exchanged.  The best thing that can be done in such cases
 	    is to minimize the effects of this until everyone has
-	    cooled back down.  That means that you should not air your
-	    angry words in public and you should not forward private
+	    cooled back down.  Do not air
+	    angry words in public and do not forward private
 	    correspondence or other private communications to public
 	    mailing lists, mail aliases, instant messaging channels or
 	    social media sites.  What people say one-to-one is often
 	    much less sugar-coated than what they would say in public,
 	    and such communications therefore have no place there -
 	    they only serve to inflame an already bad situation.  If
-	    the person sending you a flame-o-gram at least had the
+	    the person sending a flame-o-gram at least had the
 	    grace to send it privately, then have the grace to keep it
 	    private yourself.  If you feel you are being unfairly
 	    treated by another developer, and it is causing you
@@ -3628,7 +3631,7 @@ Relnotes:           yes</programlisting>
 	    <filename>src/crypto</filename>, and
 	    <filename>src/sys/contrib</filename> trees without
 	    <emphasis>explicit</emphasis> approval from the respective
-	    maintainer(s).</para>
+	    maintainers.</para>
 
 	  <para>The trees mentioned above are for contributed software
 	    usually imported onto a vendor branch.  Committing
@@ -3640,9 +3643,10 @@ Relnotes:           yes</programlisting>
 	    (or you are the maintainer), do <emphasis>not</emphasis>
 	    commit there!</para>
 
+	  <!-- FIXME: this paragraph should be rewritten -->
 	  <para>Please note that this does not mean you should not try
 	    to improve the software in question; you are still more
-	    than welcome to do so.  Ideally, you should submit your
+	    than welcome to do so.  Ideally, submit your
 	    patches to the vendor.  If your changes are
 	    &os;-specific, talk to the maintainer; they may be
 	    willing to apply them locally.  But whatever you do, do
@@ -3661,7 +3665,7 @@ Relnotes:           yes</programlisting>
 	recent release cycles and is truly no longer an &i386; centric
 	operating system.  In an effort to make it easier to keep
 	&os; portable across the platforms we support, core has
-	developed the following mandate:</para>
+	developed this mandate:</para>
 
       <blockquote>
 	<para>Our 32-bit reference platform is &arch.i386;, and our
@@ -3724,7 +3728,7 @@ Relnotes:           yes</programlisting>
       <title>Deprecating Features</title>
 
       <para>When it is necessary to remove functionality from software
-	in the base system the following guidelines should be followed
+	in the base system, follow these guidelines
 	whenever possible:</para>
 
       <orderedlist>
@@ -3782,7 +3786,7 @@ Relnotes:           yes</programlisting>
 
 	  <para>Where there are security problems that affect many
 	    different operating systems, &os; frequently depends on
-	    early access in order to be able to prepare advisories for
+	    early access to be able to prepare advisories for
 	    coordinated release.  Unless &os; developers can be
 	    trusted to maintain security, such early access will not
 	    be made available.  The Security Officer is responsible
@@ -3790,7 +3794,7 @@ Relnotes:           yes</programlisting>
 	    vulnerabilities, and for timing the release of all
 	    advisories.  He may request help under condition of
 	    confidentiality from any developer with relevant knowledge
-	    in order to prepare security fixes.</para>
+	    to prepare security fixes.</para>
 	</listitem>
 
 	<listitem>
@@ -3817,7 +3821,7 @@ Relnotes:           yes</programlisting>
 	</listitem>
 
 	<listitem>
-	  <para>Private communications should not be made
+	  <para>Private communications must not be made
 	    public without permission.</para>
 
 	  <para>Beyond the specific requirements above there is a
@@ -3831,13 +3835,13 @@ Relnotes:           yes</programlisting>
 
 	<listitem>
 	  <para>Communications on project-only or restricted access
-	    channels should be treated as private.</para>
+	    channels must be kept private.</para>
 
 	  <para>Similarly to personal communications, certain
 	    internal communications channels, including &os; Committer
 	    only mailing lists and restricted access IRC channels
-	    should be considered as private communications.  You need
-	    permission in order to publish material from these
+	    are considered private communications.  Permission is
+	    required to publish material from these
 	    sources.</para>
 	</listitem>
 
@@ -3993,7 +3997,7 @@ Relnotes:           yes</programlisting>
 	handbook.  The basics for how to get a system running must be
 	documented, although not necessarily for every single board or
 	system a Tier 2 architecture supports.  The supported hardware
-	list must exist and should be relatively recent.  It should be
+	list must exist and be relatively recent.  It should be
 	integrated into the &os; documentation.</para>
 
       <para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;,
@@ -4010,9 +4014,9 @@ Relnotes:           yes</programlisting>
 	Tier 3 platforms are architectures in the early stages of
 	development, for non-mainstream hardware platforms, or which
 	are considered legacy systems unlikely to see broad future
-	use.  Initial support for Tier 3 platforms should be worked on
+	use.  Initial support for Tier 3 platforms is worked on
 	in external SCM repositories.
-	The transition to &os;'s subversion should take place after
+	The transition to &os;'s subversion takes place after
 	the platform boots multi-user on hardware; sharing via
 	subversion is needed for wider exposure; and multiple
 	developers are actively working on the platform.
@@ -4096,12 +4100,12 @@ Relnotes:           yes</programlisting>
 	      sequence:</para>
 
 	    <screen>&prompt.root; <userinput>make install</userinput>
-&prompt.root; <userinput>make package</userinput>
-&prompt.root; <userinput>make deinstall</userinput>
-&prompt.root; <userinput>pkg add <replaceable>package you built above</replaceable></userinput>
-&prompt.root; <userinput>make deinstall</userinput>
-&prompt.root; <userinput>make reinstall</userinput>
-&prompt.root; <userinput>make package</userinput></screen>
+	      &prompt.root; <userinput>make package</userinput>
+	      &prompt.root; <userinput>make deinstall</userinput>
+	      &prompt.root; <userinput>pkg add <replaceable>package you built above</replaceable></userinput>
+	      &prompt.root; <userinput>make deinstall</userinput>
+	      &prompt.root; <userinput>make reinstall</userinput>
+	      &prompt.root; <userinput>make package</userinput></screen>
 
 	    <para>The <link
 		xlink:href="&url.books.porters-handbook;/index.html">Porters
@@ -4122,7 +4126,7 @@ Relnotes:           yes</programlisting>
 
 	    <para>Close the PR if the port came in as a PR.  To close
 	      a PR, change the state to <literal>Issue
-	      Resolved</literal> and the resolution as
+		Resolved</literal> and the resolution as
 	      <literal>Fixed</literal>.</para>
 	  </answer>
 	</qandaentry>
@@ -4148,12 +4152,12 @@ Relnotes:           yes</programlisting>
 
 		<itemizedlist>
 		  <listitem>
-		    <para>The port's PKGNAME should appear in exactly
+		    <para>The port's PKGNAME appears in exactly
 		      one line in a recent INDEX file.</para>
 		  </listitem>
 
 		  <listitem>
-		    <para>No other ports should contain any reference
+		    <para>No other ports contains any reference
 		      to the port's directory or PKGNAME in their
 		      Makefiles</para>
 
@@ -4320,8 +4324,8 @@ Relnotes:           yes</programlisting>
 	      (English-only and internationalized version).</para>
 
 	    <para>Another example is when a port is moved from one
-	      subdirectory to another, or when you want to change the
-	      name of a directory because the author(s) renamed their
+	      subdirectory to another, or when the name of a directory
+	      must be changed because the authors renamed their
 	      software even though it is a descendant of a port
 	      already in a tree.</para>
 	  </answer>
@@ -4368,8 +4372,8 @@ Relnotes:           yes</programlisting>
 		      <varname>PORTNAME</varname> instead of adding
 		      <varname>PKGNAMEPREFIX</varname> or
 		      <varname>PKGNAMESUFFIX</varname>, but this
-		      should only be done when it is really needed

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201705311204.v4VC4cLl007100>