git: 86836673be - main - Fix more typos from the original github docs

[Warner Losh]

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=86836673be10d5e844953ef89aaebfd341700148

commit 86836673be10d5e844953ef89aaebfd341700148
Author:     Warner Losh <imp at FreeBSD.org>
AuthorDate: 2021-03-17 00:43:35 +0000
Commit:     Warner Losh <imp at FreeBSD.org>
CommitDate: 2021-03-17 00:43:35 +0000

    Fix more typos from the original github docs
    
    Fix a number of typos. Note why one would prefer publishing a repo over
    phabricator. Try to minimize use of contractions. Clarify the mysterious 'source
    of truth' phrase.
    
    Noticed by: Pau Amma (except the contractions)
---
 .../en/articles/committers-guide/_index.adoc       | 60 +++++++++++-----------
 1 file changed, 29 insertions(+), 31 deletions(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index c5027a970d..5ae3aef191 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -252,18 +252,19 @@ tags are visible by default.
 
 [NOTE]
 ====
-This chapter follows the convention that the `freebsd` origin is the source of truth. If you use a different convention, replace `freebsd` with your name as appopriate.
+This chapter follows the convention that the `freebsd` origin is the origin name for the official FreeBSD git repository.
+If you use a different convention, replace `freebsd` with the name you use instead in the examples below.
 ====
 
 
-We'll explore an example for updating NetBSD's mtree that's in our
-tree. The vendor branch for this is `vendor/NetBSD/mtree`.
+We will explore an example for updating NetBSD's mtree that is in our tree.
+The vendor branch for this is `vendor/NetBSD/mtree`.
 
 ==== Updating an old vendor import
-Since the trees we have in vendor branches are usually a tiny subset of
-the FreeBSD, it's best to do them with work trees since the process is
-quite fast. Make sure that whatever directory you choose (the
-`../mtree`) argument is empty and doesn't conflict.
+The vendor trees usually have only the subset of the third-party software that is appropriate to FreeBSD.
+These trees are usually tiny in comparison to the FreeBSD tree.
+Git workrees are thus quite small and fast and the preferred method to use.
+Make sure that whatever directory you choose below (the `../mtree`) does not currently exist.
 [source,shell]
 ....
 % git worktree add ../mtree vendor/NetBSD/mtree
@@ -272,10 +273,9 @@ quite fast. Make sure that whatever directory you choose (the
 
 Prepare a full, clean tree of the vendor sources. Import everything but merge only what is needed.
 
-I have my copy of NetBSD checked out from their GitHub mirror in
-`~/git/NetBSD`, so I'll update from there: Note that "upstream" might
-have added or removed files, so we want to make sure deletions are
-propagated as well. rsync(1) is commonly installed, so I'll use that.
+This example assumes the NetBSD checked out from their GitHub mirror in `~/git/NetBSD`.
+Note that "upstream" might have added or removed files, so we want to make sure deletions are propagated as well.
+rsync(1) is commonly installed, so I'll use that.
 [source,shell]
 ....
 % cd ../mtree
@@ -295,9 +295,9 @@ Note: I run the `git diff` and `git status` commands to make sure nothing weird
 was present. Also I used `-m` to illustrate, but you should compose a proper
 message in an editor (using a commit message template).
 
-It's also important to create an annotated tag, otherwise the push
+It is also important to create an annotated tag, otherwise the push
 will be rejected. Only annotated tags are allowed to be pushed. The
-annoated tag gives you a chance to enter a commit message. Enter
+annotated tag gives you a chance to enter a commit message. Enter
 the version you are importing, along with any salient new features
 or fixes in that version.
 
@@ -336,7 +336,7 @@ The easiest way to do this would be to create a side branch with the **contents*
 % git merge freebsd/main
 ....
 
-Typically, there would be no merge conflicts here (because developers tends to work on different components).
+Typically, there would be no merge conflicts here (because developers tend to work on different components).
 In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this
 should be really rare.
 
@@ -359,9 +359,9 @@ Examine the tree against `merge_result` to make sure that you haven't missed del
 % git diff merge_result
 ....
 ==== Pushing the changes
-Once you are sure that you have a set of deltas you think is good, you can push it to
-a fork off github or gitlab for others to review. Once nice thin about Git is that it
-allows you to publish rough drafts of your work for others to review.
+Once you are sure that you have a set of deltas you think is good, you can push it to a fork off github or gitlab for others to review.
+Once nice thing about Git is that it allows you to publish rough drafts of your work for others to review.
+While phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository.
 
 After review, when you are sure it is a good change, you can push it to the FreeBSD repo:
 [source,shell]
@@ -370,11 +370,11 @@ After review, when you are sure it is a good change, you can push it to the Free
 ....
 
 === Creating a new vendor branch
-There's a number of ways to create a new vendor branch. The recommended way is
-to create a new repository and then merge that with FreeBSD. Let's say
-we're importing `glorbnitz` into the FreeBSD tree, release 3.1415. For
-the sake of simplicity, we'll not trim this release. It's a user
-command that puts the nitz device into different magical glorb states.
+There are a number of ways to create a new vendor branch.
+The recommended way is to create a new repository and then merge that with FreeBSD.
+If one is importing `glorbnitz` into the FreeBSD tree, release 3.1415.
+For the sake of simplicity, we will not trim this release.
+It is a simple user command that puts the nitz device into different magical glorb states and is small enough trimming will not save much.
 
 ==== Create the repo
 [source,shell]
@@ -388,13 +388,11 @@ command that puts the nitz device into different magical glorb states.
 At this point, you have a new repo, where all new commits will go on
 the `vendor/glorbnitz` branch.
 
-(Git professionals can also do this right in their FreeBSD clone, if they know
-how to create a new root commit that's not attached to anything, e.g.
-`git checkout --orphan vendor/glorbnitz`)
+Git experts can also do this right in their FreeBSD clone, using `git checkout --orphan vendor/glorbnitz` if they are more comfortable with that.
 
 ==== Copy the sources in
-Since this is a new import, you can just cp the sources in, or use tar or
-even rsync as shown above. And we'll add everything, assuming no dot files.
+Since this is a new import, you can just cp the sources in, or use tar or even rsync as shown above.
+And we will add everything, assuming no dot files.
 [source,shell]
 ....
 % cp -r ~/glorbnitz/* .
@@ -425,14 +423,14 @@ to an end.
 
 ==== Tag and push
 Steps from here on out are much the same as they are in the case of
-updating a vendor branch, though w/o the updating the vendor
+updating a vendor branch, though without the updating the vendor
 branch step.
 [source,shell]
 ....
 % git worktree add ../glorbnitz vendor/glorbnitz
 % cd ../glorbnitz
 % git tag --annotate vendor/glorbnitz/3.1415
-# Make sure it's good
+# Make sure the commit is good with "git show"
 % git push --follow-tags freebsd vendor/glorbnitz
 ....
 By 'good' we mean:
@@ -442,12 +440,12 @@ By 'good' we mean:
 . The vendor branch points at something sensible
 . The tag looks good, and is annotated.
 
-==== Time to finally merge it into the base tree*
+==== Time to finally merge it into the base tree
 [source,shell]
 ....
 % cd ../src
 % git subtree add -P contrib/glorbnitz vendor/glorbnitz
-# Make sure it's good
+# Make sure the commit is good with "git show"
 % git push freebsd
 ....
 Here 'good' means: