git: ccbbe1c846 - main - committers-guide: various typo fixes and slightly clearer wording

[Ceri Davies]

The branch main has been updated by ceri:

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

commit ccbbe1c84609ac07cbcd509bda004e5bdc265689
Author:     Ceri Davies <ceri at FreeBSD.org>
AuthorDate: 2021-07-22 17:02:24 +0000
Commit:     Ceri Davies <ceri at FreeBSD.org>
CommitDate: 2021-07-22 17:02:24 +0000

    committers-guide: various typo fixes and slightly clearer wording
---
 .../en/articles/committers-guide/_index.adoc       | 36 +++++++++++-----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index a8d3fe542f..55a42e54cb 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -467,7 +467,7 @@ This can make it more difficult to determine if your system needs to be updated
 ===== Building
 
 Once you've downloaded, building is done as described in the handbook,
-eg:
+e.g.:
 [source,shell]
 ....
 % cd src
@@ -617,7 +617,7 @@ For example, to encrypt for the subkey `DEADBEEF`, use `DEADBEEF!`.
 
 Commit signatures can be verified by running either `git verify-commit <commit hash>`, or `git log --show-signature`.
 
-Tag signatures can be verifed with `git verity-tag <tag name>`, or `git tag -v <tag name>`.
+Tag signatures can be verified with `git verity-tag <tag name>`, or `git tag -v <tag name>`.
 
 ////
 Commented out for now until we decide what to do.
@@ -981,7 +981,7 @@ Just do
 % git cherry-pick --abort
 % git cherry-pick -x -m 2 $HASH
 ....
-to do that. The `--aboort` will cleanup the failed first attempt.
+to do that. The `--abort` will cleanup the failed first attempt.
 
 ==== Redoing a MFC
 
@@ -1050,9 +1050,9 @@ For example, MFCs that are relevant to a PR generally include the PR field in th
 Other fields are less clear.
 For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the `main` commit with the landed commits.
 The list of reviewers is also not clear.
-If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit?  Is that true if it's identical code only, or with merely trivial reworkes? It's clearly not true for more extensive reworks.
+If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit?  Is that true if it's identical code only, or with merely trivial rework? It's clearly not true for more extensive reworks.
 Even for identical code what if the commit doesn't conflict but introduces an ABI change?  A reviewer may have ok'd a commit for `main` due to the ABI breakage but may not approve of merging the same commit as-is.
-One will have to use one's best judgement until clear guidelines can be agreed upon.
+One will have to use one's best judgment until clear guidelines can be agreed upon.
 
 For MFCs regulated by re@, new metadata fields are added, such as the Approved by tag for approved commits.
 This new metadata will have to be added via `git commit --amend` or similar after the original commit has been reviewed and approved.
@@ -1355,9 +1355,9 @@ Make sure that whatever directory you choose below (the `../mtree`) does not cur
 
 Prepare a full, clean tree of the vendor sources. Import everything but merge only what is needed.
 
-This example assumes the NetBSD checked out from their GitHub mirror in `~/git/NetBSD`.
+This example assumes the NetBSD source is 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.
+package:net/rsync[] is commonly installed, so I'll use that.
 
 [source,shell]
 ....
@@ -1377,14 +1377,14 @@ rsync(1) is commonly installed, so I'll use that.
 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 is also important to create an annotated tag, otherwise the push will be rejected.
+It is also important to create an annotated tag using `git tag -a`, otherwise the push will be rejected.
 Only annotated tags are allowed to be pushed.
 The 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.
 
 ==== Updating the FreeBSD Copy
 
-At this point you can push the import to vendor into our repo.
+At this point you can push the import to `vendor` into our repo.
 
 [source,shell]
 ....
@@ -1456,7 +1456,7 @@ Examine the tree against `merge_result` to make sure that you haven't missed del
 
 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.
 One 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.
+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:
 
@@ -1507,8 +1507,7 @@ At this point, you should have a pristine copy of glorbnitz ready to commit.
 ....
 
 As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it.
-Not everybody will know.
-But for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here.
+Not everybody will know so, for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here.
 
 ==== Now import it into our repository
 
@@ -1523,6 +1522,7 @@ Now you need to import the branch into our repository.
 
 Note the vendor/glorbnitz branch is in the repo. At this point the `/some/where/glorbnitz` can be deleted, if you like.
 It was only a means to an end.
+// perhaps the real treasure was the friends it made along the way...
 
 ==== Tag and push
 
@@ -1730,7 +1730,7 @@ on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr
 The below command merges the `working` branch into the upstream main line.
 It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.
 This syntax pushes the `working` branch to main, moving the `main` branch forward.
-You will only be able to do this if this results in a linear change to `main` (eg no merges).
+You will only be able to do this if this results in a linear change to `main` (e.g. no merges).
 
 [source,shell]
 ....
@@ -1842,7 +1842,7 @@ This section  provides a number of targeted answers to questions that are likely
 [NOTE]
 ====
 We use the common convention of having the origin for the FreeBSD repository being 'freebsd' rather than the default 'origin' to allow
-people to use that for their own development and to minimize "whoopse" pushes to the wrong repository.
+people to use that for their own development and to minimize "whoops" pushes to the wrong repository.
 ====
 
 ==== Users
@@ -2349,7 +2349,7 @@ Often pull requests are simple: requests that contain only a single commit.
 In this case, a streamlined approach may be used, though the approach in the prior section will also work.
 Here, a branch is created, the change is cherry picked, the commit message adjusted, and sanity-checked before being pushed.
 The branch `staging` is used in this example but it can be any name.
-This technique works for any number of commits in the pull request, especailly when the changes apply cleanly to the FreeBSD tree.
+This technique works for any number of commits in the pull request, especially when the changes apply cleanly to the FreeBSD tree.
 However, when there's multiple commits, especially when minor adjustments are needed, `git rebase -i` works better than `git cherry-pick`.
 Briefly, these commands create a branch; cherry-picks the changes from the pull request; tests it; adjusts the commit messages; and fast forward merges it back to `main`.
 The PR number is `$PR` below.
@@ -3058,7 +3058,7 @@ Any questions or concerns should immediately be brought to the attention of the
 [[tracking.license.grants]]
 == Keeping Track of Licenses Granted to the FreeBSD Project
 
-Various software or data exist in the repositories where the FreeBSD project has been granted a special licence to be able to use them.
+Various software or data exist in the repositories where the FreeBSD project has been granted a special license to be able to use them.
 A case in point are the Terminus fonts for use with man:vt[4].
 Here the author Dimitar Zhekov has allowed us to use the "Terminus BSD Console" font under a 2-clause BSD license rather than the regular Open Font License he normally uses.
 
@@ -3074,7 +3074,7 @@ Any developers involved in arranging such a license grant, please send details t
 * A note of any restrictions, limitations or exceptions that apply specifically to FreeBSD's usage of the licensed material.
 * Any other relevant information.
 
-Once the {core-email} is satisfied that all the necessary details have been gathered and are correct, the secretary will send a PGP-signed acknowledgement of receipt including the license details.
+Once the {core-email} is satisfied that all the necessary details have been gathered and are correct, the secretary will send a PGP-signed acknowledgment of receipt including the license details.
 This receipt will be persistently archived and serve as our permanent record of the license grant.
 
 The license archive should contain only details of license grants; this is not the place for any discussions around licensing or other subjects.
@@ -3087,7 +3087,7 @@ The project uses https://spdx.dev[SPDX] tags in our source base.
 At present, these tags are indented to help automated tools reconstruct license requirements mechanically.
 All _SPDX-License-Identifier_ tags in the tree should be considered to be informative.
 All files in the FreeBSD source tree with these tags also have a copy of the license which governs use of that file.
-In the event of a discrepency, the verbatim license is controlling.
+In the event of a discrepancy, the verbatim license is controlling.
 The project tries to follow the https://spdx.github.io/spdx-spec/[SPDX Specification, Version 2.2].
 How to mark source files and valid algebraic expressions are found in https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/[Appendix IV] and https://spdx.github.io/spdx-spec/appendix-V-using-SPDX-short-identifiers-in-source-files/[Appendix V].
 The project draws identifiers from SPDX's list of valid https://spdx.org/licenses/[short license identifiers].