diff --git a/site/book/01-getting-started/02-quickstart.md b/site/book/01-getting-started/02-quickstart.md index d3fde2a949..66c833216d 100644 --- a/site/book/01-getting-started/02-quickstart.md +++ b/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`: diff --git a/site/book/03-packages/01-getting-a-package.md b/site/book/03-packages/01-getting-a-package.md index 049eb43e5a..0c37dddcbb 100644 --- a/site/book/03-packages/01-getting-a-package.md +++ b/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` diff --git a/site/book/03-packages/03-editing-a-package.md b/site/book/03-packages/03-editing-a-package.md index 434589ee9d..f2ba31b140 100644 --- a/site/book/03-packages/03-editing-a-package.md +++ b/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/ diff --git a/site/book/03-packages/04-updating-a-package.md b/site/book/03-packages/04-updating-a-package.md index 8796d3d882..b154501bc3 100644 --- a/site/book/03-packages/04-updating-a-package.md +++ b/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/ diff --git a/site/book/03-packages/06-composing-a-package.md b/site/book/03-packages/06-composing-a-package.md index 4983a6f1ec..0f4f075f41 100644 --- a/site/book/03-packages/06-composing-a-package.md +++ b/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. diff --git a/site/book/03-packages/07-publishing-a-package.md b/site/book/03-packages/07-publishing-a-package.md index ced7482ac0..59f2d8bcdc 100644 --- a/site/book/03-packages/07-publishing-a-package.md +++ b/site/book/03-packages/07-publishing-a-package.md @@ -30,7 +30,7 @@ You can then fetch the published package: $ kpt pkg get /@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.