book: Address feedback from M2-2 fishfood. (#1878)

site/book/01-getting-started/02-quickstart.md

@@ -32,7 +32,7 @@ will explain the `Kptfile` in detail.
 Initialize a local Git repo and commit the forked copy of the package:
 
 ```shell
-git init; git add .; git commit -am "Pristine nginx package"
+$ git init; git add .; git commit -am "Pristine nginx package"
 ```
 
 ## Customize the package
@@ -127,7 +127,7 @@ the upstream changes with changes to your local package.
 First, commit your local changes:
 
 ```shell
-git add .; git commit -am "My customizations"
+$ git add .; git commit -am "My customizations"
 ```
 
 Then update to version `v0.3`:

site/book/03-packages/01-getting-a-package.md

@@ -105,10 +105,9 @@ follows the familiar structure of KRM resources, the name of the package is also
 `metadata.name` field. This must always be the name of the directory, and kpt will update it
 automatically when forking a package. In this case, `metadata.name` is set to `mywordpress`.
 
-The name of a package is unique within its parent package, but it may not be unique in a deeply
-nested package hierarchy (i.e. Depth > 2). The _unique identifier_ for a package is defined as the
-relative path from the top package to the subpackage. For example, we could have two subpackages
-with the name `mysql` having the following identifiers:
+In general, the package name is not unique. The _unique identifier_ for a
+package is defined as the relative path from the top package to the subpackage. For example, we
+could have two subpackages with the name `mysql` having the following identifiers:
 
 - `wordpress/backend/mysql`
 - `wordpress/frontend/mysql`

site/book/03-packages/03-editing-a-package.md

@@ -16,6 +16,14 @@ the package. This process can be manual or automated depending on your use case.
 We will cover package composition later in this chapter. For now, let's focus on editing resources
 _within_ a package.
 
+## Initialize the local repo
+
+Before we make any changes to package, we should first initialize and commit the pristine package:
+
+```shell
+$ git init; git add .; git commit -am "Pristine wordpress package"
+```
+
 ## Manual edits
 
 As mentioned earlier, you can manually edit or author KRM resources using your favorite editor.
@@ -39,11 +47,25 @@ For example, setting a label on all the resources in the `wordpress` package can
 using the following function:
 
 ```shell
-$ cd wordpress
-$ kpt fn eval --image gcr.io/kpt-fn/set-label:v0.1 -- env=dev
+$ kpt fn eval --image gcr.io/kpt-fn/set-label:v0.1 wordpress -- env=dev
 ```
 
 [Chapter 4] discusses different ways of running functions in detail.
 
+## Commit your changes
+
+Regardless of how you edited the package, you can see the changes compared to the
+pristine copy:
+
+```shell
+$ git diff
+```
+
+If you're happy with the changes, commit them:
+
+```shell
+$ git add .; git commit -am "My customizations"
+```
+
 [cloud code]: https://cloud.google.com/code
 [chapter 4]: /book/04-using-functions/

site/book/03-packages/04-updating-a-package.md

@@ -39,6 +39,12 @@ strategy is used which performs a structural comparison of the resource using Op
 
 > Refer to the [command reference][update-doc] for more details.
 
-[update-doc]: /reference/pkg/update/
-
 TODO(#1827): Handling merge conflicts
+
+Once you have successfully updated the package, commit the changes:
+
+```shell
+$ git add .; git commit -am "Updated wordpress to v0.2"
+```
+
+[update-doc]: /reference/pkg/update/

site/book/03-packages/06-composing-a-package.md

@@ -36,9 +36,8 @@ We're going to add back the `mysql` subpackage using the two different approache
 ### Create a new package
 
 ```shell
-$ cd wordpress
-$ mkdir mysql
-$ kpt pkg init mysql
+$ mkdir wordpress/mysql
+$ kpt pkg init wordpress/mysql
 # author resources in mysql
 ```
 
@@ -47,12 +46,10 @@ This creates a [dependent package].
 ### Get an existing package
 
 ```shell
-$ cd wordpress
-$ kpt pkg get https://github.com/kubernetes/website.git/content/en/examples/application/mysql@snapshot-initial-v1.20
+$ rm -rf wordpress/mysql
+$ kpt pkg get https://github.com/kubernetes/website.git/content/en/examples/application/mysql@snapshot-initial-v1.20 wordpress/mysql
 ```
 
-TODO(#1829): This can be simplified.
-
 This creates an [independent package]. If you wish to make this a dependent package, you
 can delete the `upstream` and `upstreamLock` sections of the `Kptfile` in `mysql` directory.
 

site/book/03-packages/07-publishing-a-package.md

@@ -30,7 +30,7 @@ You can then fetch the published package:
 $ kpt pkg get <MY_REPO_URL>/@v0.1
 ```
 
-## Per-directory Versioning
+## Monorepo Versioning
 
 You may have a Git repo containing multiple packages. kpt provides a tagging
 convention to enable packages to be independently versioned.