Further work on packaging guide (proofreading)

1 files changed, 82 insertions, 68 deletions

diff --git a/doc/packaging.cli b/doc/packaging.cli
index dd08e82..341a8c8 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -3550,7 +3550,7 @@ this role.
 
 \N|In extraordinary circumstances the \c{build2-packaging} administrators may
 make direct changes to the package, for example, to release a new revision in
-order to address a critical issues. They will still try to coordinate the
+order to address a critical issue. They will still try to coordinate the
 changes with the maintainer but may not always be able to wait for a response
 in time-sensitive cases.|
 
@@ -3559,10 +3559,10 @@ in time-sensitive cases.|
 As you may recall, our package currently has a pre-release snapshot version of
 the upstream version (see \l{#core-package-adjust-version Adjust package
 version}). Once all the changes are in, we can change to the final upstream
-version, in a sense signalling that this package version is ready.
+version, in a sense signaling that this package version is ready.
 
-\N|If you are working in a branch, then now is the time to merge it into
-\c{master}.|
+\N|If you are working in a branch, then now is also the time to merge it into
+\c{master} (or equivalent).|
 
 The recommended way to do this is with the \l{bdep-release(1)} command (see
 \l{intro#guide-versioning-releasing Versioning and Release Management} for
@@ -3580,8 +3580,8 @@ $ cd foo/ # Change to the package repository root.
 $ bdep release --no-open --show-push
 \
 
-Then review the commit made by \c{bdep-release} and push the changes by
-copying the command that it printed:
+Then review the commit made by \c{bdep-release} and, if everything looks good,
+push the changes by copying the command that it printed:
 
 \
 $ git diff HEAD~1
@@ -3607,7 +3607,7 @@ $ cd foo/ # Change to the package repository root.
 $ bdep publish
 \
 
-The \c{bdep-publish} command prepares the source distributin of your package,
+The \c{bdep-publish} command prepares the source distribution of your package,
 uploads the resulting archive to the package repository, and prints a link to
 the package submission in the queue. Open this link in the browser and check
 that there are no surprises in build results (they should match the earlier CI
@@ -3618,28 +3618,31 @@ compared to our earlier CI submissions, the way the packages are built on CI
 and in the package repository are not exactly the same. Specifically, CI
 builds them from \c{git} while the package repository \- from the submitted
 package archives. If there are differences, it's almost always due to issues
-in the source distribution preparation \l{#core-test-smoke-locally-dist Test
-locally: distribution}.|
+in the source distribution preparation (see \l{#core-test-smoke-locally-dist
+Test locally: distribution}).|
 
 If everything looks good, then you are done: the package submission will be
 reviewed and, if there are no problems, moved to \l{https://cppget.org
 cppget.org}. If there are problems, then an issue will be created in the
 package repository with the review feedback. In this case you will need to
 \l{#core-version-management-new-revision release and publish a version
-revision} to address these problems. But in both cases you should first read
-through \l{#core-version-management Package version management} to understand
-the recommended \"version lifecycle\" of a third-party package.
+revision} to address any problems. However, in both cases, you should first
+read through the following \l{#core-version-management Package version
+management} section to understand the recommended \"version lifecycle\" of a
+third-party package.
 
 Also, if there is an issue for this package in
 \l{https://github.com/build2-packaging/WISHLIST
 github.com/build2-packaging/WISHLIST}, then you would want to add a comment
-and close it once the package has been published.
+and close it once the package has been moved to \l{https://cppget.org
+cppget.org}.
 
 
 \h#core-version-management|Package version management|
 
-Once we have pushed the release commit, in order to preserve continous
-versioning, no further changes should be made to the package without also
+Once we have pushed the release commit, in order to preserve continuous
+versioning (see \l{#core-package-adjust-version Adjust package version} for
+background), no further changes should be made to the package without also
 changing its version.
 
 \N|More precisely, you can make and commit changes without changing the
@@ -3650,21 +3653,22 @@ package remains unchanged.|
 
 While in our own projects we can change the versions as we see fit, with
 third-party projects the versions are dictated by the upstream and as a result
-we are limited to what we can use to fix issues in the package itself. It may
-be tempting (and maybe even conceptually correct) to release a patch version
-for our own fixes, however, we will be in trouble if later upstream releases
-the same patch version but with a different set of changes (plus the users of
-our package may wonder where did this version come from). As a result, we
-should only change the major, minor, or patch components of the package
-version in response to the corresponding upstream releases. For fixes to the
-package itself we should instead use version revisions.
+we are limited to what we can use to fix issues in our packaging work
+itself. It may be tempting (and perhaps even conceptually correct) to release
+a patch version for our own fixes, however, we will be in trouble if later
+upstream releases the same patch version but with a different set of changes
+(plus the users of our package may wonder where did this version come
+from). As a result, we should only change the major, minor, or patch
+components of the package version in response to the corresponding upstream
+releases. For fixes to the packaging work itself we should instead use version
+revisions.
 
 \N|Because a revision replaces the existing version, we should try to limit
-revision changes to bug fixes and preferably only to the package
+revision changes to bug fixes and preferably only in the package
 \"infrastructure\" (\c{buildfiles}, \c{manifest}, etc). Fixes to upstream
-source code should be limited to critical bugs, preferably be backported from
-upstream. To put it another way, changes in a revision should have an even
-more limited scope than a patch release.|
+source code should be limited to critical bugs and be preferably backported
+from upstream. To put it another way, changes in a revision should have an
+even more limited scope than a patch release.|
 
 Based on this, the recommended \"version lifecycle\" for a third-party
 package is as follows:
@@ -3674,25 +3678,28 @@ package is as follows:
 \li|After a release (the \l{#core-release-publish-release Release final
 version} step above), for example, version \c{2.1.0}, the package enters a
 \"revision phase\" where we can release revisions (\c{2.1.0+1}, \c{2.1.0+2},
-etc) to address any issues in the package. See
-\l{#core-version-management-new-revision New revision} for details.|
+etc) to address any issues in the packaging work. See
+\l{#core-version-management-new-revision New revision} for the detailed
+procedure.|
 
 \li|When a new upstream version is released, for example version \c{2.2.0},
 and we wish to upgrade our package to this version, we switch to its
-pre-release snapshot version (\c{2.2.0-a.0.z}) the same as we did on the
+pre-release snapshot version (\c{2.2.0-a.0.z}) the same way as we did on the
 \l{#core-package-adjust-version Adjust package version} step initially. See
-\l{#core-version-management-new-version New version} for details.|
+\l{#core-version-management-new-version New version} for the detailed
+procedure.|
 
 \li|Once we are done upgrading to the new upstream version, we release the
 final version just like on the \l{#core-release-publish-release Release final
-version} step initially.||
+version} step initially. At this point the package enters another revision
+phase.||
 
 Note also that in the above example, once we have switched to \c{2.2.0-a.0.z},
 we cannot go back and release another revision or patch version for \c{2.1.0}
 on the current branch. Instead, we will need to create a separate branch for
 the \c{2.1.Z} release series and make a revision or patch version there. See
 \l{#core-version-management-old-series New version/revision in old release
-series} for details.
+series} for the detailed procedure.
 
 
 \h2#core-version-management-new-revision|New revision|
@@ -3709,9 +3716,10 @@ accumulated issues} for background.|
 
 In the revision phase of the package version lifecycle (i.e., when the version
 does not end with \c{-a.0.z}), every commit must be accompanies by the
-revision increment to maintain continous verisions. As a result, each revision
-release commit also contains the changes in this revision. Below is a typical
-workflow for releasing and publishing the revision:
+revision increment to maintain continuous versioning. As a result, each
+revision release commit necessarily also contains the changes in this
+revision. Below is a typical workflow for releasing and publishing the
+revision:
 
 \
 $ # make changes
@@ -3726,7 +3734,7 @@ $ bdep publish
 
 Customarily, the revision commit message has the \c{\"Release version
 X.Y.Z+R\"} summary as generated by \c{bdep-release} followed by the
-description of changes organized in a list of there are several. For example:
+description of changes, organized in a list if there are several. For example:
 
 \
 Release version 2.1.0+1
@@ -3776,7 +3784,8 @@ $ bdep publish
 \h2#core-version-management-new-version|New version|
 
 As discussed in \l{#core-version-management Package version management}, we
-release new versions in reponse to the corresponding upstream releases.
+release new versions strictly in response to the corresponding upstream
+releases.
 
 The amount or work required to upgrade a package to a new upstream version
 depends on the extend of changes in the new version.
@@ -3785,8 +3794,8 @@ On one extreme you may have a patch release which fixes a couple of bugs in
 the upstream source code without any changes to the set of source files,
 upstream build system, etc. In such cases, upgrading a package is a simple
 matter of creating a new work branch, pointing the \c{upstream} \c{git}
-submodule to the new release, running tests, and releasing and publishing a
-new package version.
+submodule to the new release, running tests, and then merging, releasing, and
+publishing a new package version.
 
 On the other extreme you may have a new major upstream release which is
 essentially a from-scratch rewrite with new source code layout, different
@@ -3803,19 +3812,23 @@ in the upstream build system, etc.
 
 The following sections provide a checklist-like sequence of steps that can be
 used to review upstream changes with links to the relevant earlier sections in
-case undjustments are required.
+case adjustments are required.
 
 
 \h2#core-version-management-new-version-branch|New version: create new work branch|
 
 When upgrading a package to a new upstream version it's recommended to do this
-in a new work branch which, upon completion, is merged into \c{master}. For
-example, if the new upstream version is \c{2.2.0}:
+in a new work branch which, upon completion, is merged into \c{master} (or
+equivalent). For example, if the new upstream version is \c{2.2.0}:
 
 \
 $ git checkout -b wip-2.2.0
 \
 
+\N|If you are not the maintainer of the package and would like to help with
+preparing the new version, then, when everything is ready, use this branch
+to create a pull request instead of merging it directly.|
+
 
 \h2#core-version-management-new-version-open|New version: open new version|
 
@@ -3839,7 +3852,7 @@ new version.
 
 For example, if the upstream release tag we are interested in is called
 \c{v2.2.0}, to update the \c{upstream} submodule to point to this release
-commit, run the following command:
+commit, run the following commands:
 
 \
 $ cd upstream/
@@ -3881,7 +3894,7 @@ particular (discussed in the following sections):
 
 \li|New dependencies being added or old removed.|
 
-\li|New source files beging added or old removed (including in tests, etc).|
+\li|New source files being added or old removed (including in tests, etc).|
 
 \li|Changes to the upstream build system.|
 
@@ -3891,18 +3904,18 @@ particular (discussed in the following sections):
 \h2#core-version-management-new-version-layout|New version: layout changes|
 
 As mentioned earlier, for drastic layout changes it may make sense to start
-from scratch and re-generate the package with the \c{bdep-new} command
-(\l{#core-package-struct Decide on the package source code layout} starting
-point). On the other hand, if the changes are minor, then you can try to
-adjust things manually. An in-between strategy is to generate the new layout
-using \c{bdep-new} on the side and then retrofit the relevant changes in
-\c{buildfiles} to the existing package. In a sense, this approach uses
+from scratch and re-generate the package with the \c{bdep-new} command (use
+\l{#core-package-struct Decide on the package source code layout} as a
+starting point). On the other hand, if the changes are minor, then you can try
+to adjust things manually. An in-between strategy is to generate the new
+layout using \c{bdep-new} on the side and then retrofit the relevant changes
+in \c{buildfiles} to the existing package. In a sense, this approach uses
 \c{bdep-new} as a guide to figure out how to implement the new layout.
 
 
-\h2#core-version-management-new-version-dependecies|New version: new/old dependencies|
+\h2#core-version-management-new-version-dependencies|New version: new/old dependencies|
 
-If upsream added new or removed old dependecies, then you will need to
+If upstream added new or removed old dependencies, then you will need to
 replicate these changes in your package as on the \l{#core-fill-depend Add
 dependencies} and \l{#core-adjust-build-src-source-dep Adjust source
 \c{buildfile}: dependencies} initial packaging steps.
@@ -3910,9 +3923,9 @@ dependencies} and \l{#core-adjust-build-src-source-dep Adjust source
 
 \h2#core-version-management-new-version-sources|New version: new/old source files|
 
-If upsream added new or removed old source files, then you will need to
-replicate these changes in your package as on the \c{#core-fill-source Fill
-with upstream source code} and possibly \c{#core-adjust-build-src-header
+If upstream added new or removed old source files, then you will need to
+replicate these changes in your package as on the \l{#core-fill-source Fill
+with upstream source code} and possibly \l{#core-adjust-build-src-header
 Adjust header \c{buildfile}} and \l{#core-adjust-build-src-source-src Adjust
 source \c{buildfile}: sources, private headers} initial packaging steps.
 
@@ -3923,12 +3936,12 @@ remove old source files (typically new tests). See
 If there are any manual modifications to the upstream source code, then you
 will also need to re-apply them to the new version as discussion in
 \l{#howto-patch-upstream-source-manual Modifying upstream source code
-manually?}
+manually}.
 
 
 \h2#core-version-management-new-version-build|New version: changes to build system|
 
-If upsream changed anything in the build system, then you may need to
+If upstream changed anything in the build system, then you may need to
 replicate these changes in your package's \c{buildfiles}. The relevant initial
 packaging steps are: \l{#core-adjust-build-wide Adjust project-wide build system files in
 \c{build/}} and \l{#core-adjust-build-src-source-opt Adjust source
@@ -3941,7 +3954,7 @@ project-wide build system files in \c{tests/build/}} and
 
 \h2#core-version-management-new-version-other|New version: other new/old files/subdirectories|
 
-If upsream added or removed any other files or subdirectories that are
+If upstream added or removed any other files or subdirectories that are
 relevant to our package (such as documentation), then adjust the package
 similar to the \l{#core-root-buildfile Adjust root \c{buildfile}} and
 \l{#core-root-buildfile-doc Adjust root \c{buildfile}: other subdirectories}
@@ -3962,17 +3975,17 @@ always be able to fix it immediately (for example, by
 \l{#core-version-management-new-revision releasing a revision}). This could be
 because the change is too extensive/risky for a revision or simply not
 critical enough to warrant a release. In such cases it's recommended to file
-an issue in the package's repository with the view to fix it when the next
+an issue in the package repository with the view to fix it when the next
 opportunity arises. Releasing a new upstream version is one such opportunity
 and it makes sense to review any accumulated package issues and see if any
-of them can be addressed.
+of them could be addressed.
 
 
 \h2#core-version-management-new-version-test|New version: test locally and with CI|
 
 Once all the adjustments are in, test the package both locally and with CI
-similart to how we did after completing the smoke test during the initial
-packaging:
+similar to how we did it during the initial packaging after completing the
+smoke test:
 
 \l{#core-test-smoke-locally Test locally}\n
 \l{#core-test-smoke-locally-install Test locally: installation}\n
@@ -3983,7 +3996,7 @@ packaging:
 \h2#core-version-management-new-version-release|New version: merge, release, and publish|
 
 When the new version of the package is ready to be released, merge the
-work branch to \c{master}:
+work branch to \c{master} (or equivalent):
 
 \
 $ git checkout master
@@ -3997,10 +4010,10 @@ Then release and publish using the same steps as after the initial packaging:
 \h2#core-version-management-old-series|New version/revision in old release series|
 
 As discussed in \l{#core-version-management Package version management}, if we
-have already switched to the next upstream version in the \c{master} branch,
-we cannot go back and release a new version or a revision for an older release
-series on the same branch. Instead, we need to create a seperate, long-lived
-branch for this work.
+have already switched to the next upstream version in the \c{master} (or
+equivalent) branch, we cannot go back and release a new version or revision
+for an older release series on the same branch. Instead, we need to create a
+separate, long-lived branch for this work.
 
 As an example, let's say we need to release another revision or a patch
 version for an already released \c{2.1.0} while our \c{master} branch has
@@ -4035,6 +4048,7 @@ it corresponds to the \c{2.Y.Z} release series. If you already have the
 
 \h1#dont-do|What Not to Do|
 
+@@
 
 \h#dont-from-scratch|Don't write \c{buildfiles} from scratch, use \c{bdep-new}|