From 945eb4eb4b4cfea749918bc9461292b6f553c00a Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 10:05:05 +0300 Subject: [PATCH 1/8] Refactor docs folder The content of the docs folder is not documentation, therefore it was refactored - Docs style guide moved to the README.md of the documentation and was extended with the Nephio documentation guide what is followed by the Porch documentation - ROADMAP.md was removed as it was outdated and we follow the roadmap in a GitHub Project now - The folder was renamed to `architecture` Signed-off-by: Gergely Csatari --- README.md | 2 +- .../design-docs/00-template.md | 0 .../design-docs/01-live-invenstory-to-rg.md | 0 .../design-docs/02-oci-support.md | 0 .../design-docs/03-pipeline-merge.md | 0 .../design-docs/04-arm-build.md | 0 .../design-docs/05-kpt-fn-exclude.md | 0 {docs => architecture}/style-guides/errors.md | 0 .../sync/prototype-controller.md | 0 docs/ROADMAP.md | 43 ------------ docs/style-guides/docs.md | 42 ----------- documentation/README.md | 69 +++++++++++++++++++ 12 files changed, 70 insertions(+), 86 deletions(-) rename {docs => architecture}/design-docs/00-template.md (100%) rename {docs => architecture}/design-docs/01-live-invenstory-to-rg.md (100%) rename {docs => architecture}/design-docs/02-oci-support.md (100%) rename {docs => architecture}/design-docs/03-pipeline-merge.md (100%) rename {docs => architecture}/design-docs/04-arm-build.md (100%) rename {docs => architecture}/design-docs/05-kpt-fn-exclude.md (100%) rename {docs => architecture}/style-guides/errors.md (100%) rename {docs => architecture}/sync/prototype-controller.md (100%) delete mode 100644 docs/ROADMAP.md delete mode 100644 docs/style-guides/docs.md diff --git a/README.md b/README.md index f5b74fa715..06a6856ad3 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ The kpt toolchain includes the following components: ## Roadmap -You can read about the big upcoming features in the [roadmap doc](/docs/ROADMAP.md). +You can floow the kpt roadmap in the related [GitHub Project](https://github.com/orgs/kptdev/projects/2/views/2) ## Contributing diff --git a/docs/design-docs/00-template.md b/architecture/design-docs/00-template.md similarity index 100% rename from docs/design-docs/00-template.md rename to architecture/design-docs/00-template.md diff --git a/docs/design-docs/01-live-invenstory-to-rg.md b/architecture/design-docs/01-live-invenstory-to-rg.md similarity index 100% rename from docs/design-docs/01-live-invenstory-to-rg.md rename to architecture/design-docs/01-live-invenstory-to-rg.md diff --git a/docs/design-docs/02-oci-support.md b/architecture/design-docs/02-oci-support.md similarity index 100% rename from docs/design-docs/02-oci-support.md rename to architecture/design-docs/02-oci-support.md diff --git a/docs/design-docs/03-pipeline-merge.md b/architecture/design-docs/03-pipeline-merge.md similarity index 100% rename from docs/design-docs/03-pipeline-merge.md rename to architecture/design-docs/03-pipeline-merge.md diff --git a/docs/design-docs/04-arm-build.md b/architecture/design-docs/04-arm-build.md similarity index 100% rename from docs/design-docs/04-arm-build.md rename to architecture/design-docs/04-arm-build.md diff --git a/docs/design-docs/05-kpt-fn-exclude.md b/architecture/design-docs/05-kpt-fn-exclude.md similarity index 100% rename from docs/design-docs/05-kpt-fn-exclude.md rename to architecture/design-docs/05-kpt-fn-exclude.md diff --git a/docs/style-guides/errors.md b/architecture/style-guides/errors.md similarity index 100% rename from docs/style-guides/errors.md rename to architecture/style-guides/errors.md diff --git a/docs/sync/prototype-controller.md b/architecture/sync/prototype-controller.md similarity index 100% rename from docs/sync/prototype-controller.md rename to architecture/sync/prototype-controller.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 189220cdfb..0000000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,43 +0,0 @@ -# kpt roadmap - -Last updated: February 9th, 2023 - -Please follow the [installation](https://kpt.dev/installation/kpt-cli/) guide for installing the latest version of kpt. - -## Latest releases - -https://github.com/kptdev/kpt/releases - -## Detailed release notes -Please refer to the [release notes] page for more information about the latest features. - -## Upcoming features - -A few areas of work are ongoing. (This is not exhaustive.) - -### Explore various options for function runtime - -Currently, `kpt fn render` has dependency on docker to execute functions in pipeline. -There are performance and docker dependency issues reported by customers. We will -be exploring different function runtimes in order to address those issues. This is -just an exploratory step and actual implementation if any, will be taken up after December 2021. -[Tracking issue](https://github.com/kptdev/kpt/issues/2567). - -### Additional storage beyond Git - -Currently, `kpt pkg` workflows only support Git repositories. There is some increasing -demand from users to support other storage options beyond git(e.g., OCI). We will -be spending time understanding the use-cases and need for this project. [Tracking issue](https://github.com/kptdev/kpt/issues/2300). - -## Feedback channels: -1. File a [new issue] on Github, but please search first. - - -[new issue]: https://github.com/kptdev/kpt/issues/new/choose -[The Kpt Book]: https://kpt.dev/book/ -[apply chapter]: https://kpt.dev/book/06-apply/ -[cli-utils]: https://github.com/kubernetes-sigs/cli-utils -[function catalog]: https://catalog.kpt.dev/ -[kpt milestones]: https://github.com/kptdev/kpt/milestones -[migration guide]: https://kpt.dev/installation/migration -[release notes]: https://github.com/kptdev/kpt/releases diff --git a/docs/style-guides/docs.md b/docs/style-guides/docs.md deleted file mode 100644 index 6432eaea5f..0000000000 --- a/docs/style-guides/docs.md +++ /dev/null @@ -1,42 +0,0 @@ -# kpt Docs Style Guide - -1. CLI commands name should appear with inline quotes everywhere including in - page titles: - - Correct: `diff` - - Incorrect: `Diff` - - Incorrect: `The Diff tool` -2. Shell commands should be in `shell` code blocks and should contain exactly - one command specifing using`$`: - - ```shell - $ kpt - - ``` - -3. Links to other kpt doc pages should be absolute: - - Correct: `[pkg]: /reference/cli/pkg/get/` - - Incorrect: `[pkg]: ../../../reference/cli/pkg/get` -4. Flags must appear after positional args: - - - Correct: - - ```shell - $ kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace - ``` - - - Incorrect: - - ```shell - $ kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package - ``` - -5. The name of the tool should always appear as small caps (even at start of - sentences) and not in block quotes: - - Correct: kpt - - Incorrect: `kpt` - - Incorrect: Kpt - - Incorrect: KPT -6. References to a particular KRM group, version, kind, field should appear with - inline quotes: - - Correct: `ConfigMap` - - Incorrect: ConfigMap diff --git a/documentation/README.md b/documentation/README.md index e914e5db37..7a0ccb2097 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -33,6 +33,75 @@ The site pulls some dependencies via Git submodules. If `npm install` succeeds b git submodule update --init --recursive ``` +## Style guide for documentation + +1. Use US English in the documentation + +2. Do not add manually a table of contents to the documents. Hugo and Docsy takes care of this. + +3. Do not use H1 (#) headers in the documents. Docsy generates a H1 header to every document + consistent with the title of the document. Start the headings with H2 (##) + +4. Use the built in alerts for notes and alerts + + ```go-html-template + {{%/* alert title="Warning" color="primary" */%}} + This is a note. + {{%/* /alert */%}} + ``` + + ```go-html-template + {{%/* alert title="Warning" color="warning" */%}} + This is a warning. + {{%/* /alert */%}} + ``` + +5. If you add any commands to the content inline surround the comand with backticks (\` \`), like \`ls -la\` + +6. Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics +(\* \*) to mark any inline IP address, domain name, file name, file location or similar. + +7. Whenever possible define the type of code for your code blocks + * \```shell for all shell blocks + * \```golang for all Go blocks + * \```yaml for all YAML blocks + * \``` yang for all YANG blocks + * a full list of language identifyers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) + + +8. Links to other kpt doc pages should be absolute: + - Correct: `[pkg]: /reference/cli/pkg/get/` + - Incorrect: `[pkg]: ../../../reference/cli/pkg/get` + +9. Flags must appear after positional args: + + - Correct: + + ```shell + $ kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace + ``` + + - Incorrect: + + ```shell + $ kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package + ``` + +10. The name of the tool should always appear as small caps (even at start of + sentences) and not in block quotes: + - Correct: kpt + - Incorrect: `kpt` + - Incorrect: Kpt + - Incorrect: KPT + +11. References to a particular KRM group, version, kind, field should appear with + inline quotes: + - Correct: `ConfigMap` + - Incorrect: ConfigMap + +12. Do not add any TBDs to the documentation. If something is missing create an [issue](https://github.com/kptdev/kpt/issues) for it + + ## License Licensed under the [Creative Commons Attribution 4.0 International license](LICENSE-documentation) From 2ebaad3903c063a42a748e82b4fbefda63ea5386 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 14:53:51 +0300 Subject: [PATCH 2/8] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- documentation/README.md | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 06a6856ad3..bcf36e7cf3 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ The kpt toolchain includes the following components: ## Roadmap -You can floow the kpt roadmap in the related [GitHub Project](https://github.com/orgs/kptdev/projects/2/views/2) +You can follow the kpt roadmap in the related [GitHub Project](https://github.com/orgs/kptdev/projects/2/views/2). ## Contributing diff --git a/documentation/README.md b/documentation/README.md index 7a0ccb2097..b15f2bfe09 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -37,12 +37,12 @@ git submodule update --init --recursive 1. Use US English in the documentation -2. Do not add manually a table of contents to the documents. Hugo and Docsy takes care of this. +2. Do not manually add a table of contents to the documents. Hugo and Docsy take care of this. -3. Do not use H1 (#) headers in the documents. Docsy generates a H1 header to every document +3. Do not use H1 (#) headers in the documents. Docsy generates an H1 header for every document consistent with the title of the document. Start the headings with H2 (##) -4. Use the built in alerts for notes and alerts +4. Use the built-in alerts for notes and alerts ```go-html-template {{%/* alert title="Warning" color="primary" */%}} @@ -56,17 +56,17 @@ git submodule update --init --recursive {{%/* /alert */%}} ``` -5. If you add any commands to the content inline surround the comand with backticks (\` \`), like \`ls -la\` +5. If you add any commands to the content inline, surround the command with backticks (\` \`), like `ls -la` -6. Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics -(\* \*) to mark any inline IP address, domain name, file name, file location or similar. +6. Do not surround IP addresses, domain names, or any other identifiers with backticks. Use italics +(\* \*) to mark any inline IP address, domain name, file name, file location, or similar. -7. Whenever possible define the type of code for your code blocks +7. Whenever possible, define the type of code for your code blocks * \```shell for all shell blocks * \```golang for all Go blocks * \```yaml for all YAML blocks - * \``` yang for all YANG blocks - * a full list of language identifyers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) + * \```yang for all YANG blocks + * a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) 8. Links to other kpt doc pages should be absolute: From 69e832be1152e5c1ffd4d6df3ef274b3bdcad4af Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 14:59:55 +0300 Subject: [PATCH 3/8] Update broken links Signed-off-by: Gergely Csatari --- CONTRIBUTING.md | 4 ++-- documentation/content/en/faq.md | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c788cfa5c..f0c0c7c078 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -178,8 +178,8 @@ Docs are under [documentation/](documentation/). Refer to the [README.md](docume documentation contributions. -[error message style guide]: docs/style-guides/errors.md -[documentation style guide]: docs/style-guides/docs.md +[error message style guide]: architecture/style-guides/errors.md +[documentation style guide]: documentation/README.md#styl-guide-for-documentation [github help]: https://help.github.com/articles/about-pull-requests/ [google's open source community guidelines]: https://opensource.google.com/conduct/ diff --git a/documentation/content/en/faq.md b/documentation/content/en/faq.md index 4e5749f639..9aac641ccf 100644 --- a/documentation/content/en/faq.md +++ b/documentation/content/en/faq.md @@ -2,7 +2,7 @@ ### What is the roadmap for kpt? -Please visit the [roadmap document] and the [kpt milestones]. +Please visit the [roadmap GitHub Project](https://github.com/orgs/kptdev/projects/2) and the [kpt milestones]. ### How is kpt different from other solutions? @@ -131,8 +131,6 @@ don't have to alias it. It is pronounced "kept". [using functions]: /book/04-using-functions/ [contact]: /contact/ [functions catalog]: https://catalog.kpt.dev/ -[roadmap document]: - https://github.com/kptdev/kpt/blob/main/docs/ROADMAP.md [kpt milestones]: https://github.com/kptdev/kpt/milestones [kustomize solution]: https://github.com/kptdev/kpt/tree/main/package-examples/kustomize From 7403ab367cfb6019806cd2fbc384877872e29664 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 15:59:33 +0300 Subject: [PATCH 4/8] Fix notes examples Signed-off-by: Gergely Csatari --- documentation/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index b15f2bfe09..41056427e9 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -44,17 +44,17 @@ git submodule update --init --recursive 4. Use the built-in alerts for notes and alerts - ```go-html-template - {{%/* alert title="Warning" color="primary" */%}} - This is a note. - {{%/* /alert */%}} - ``` - - ```go-html-template - {{%/* alert title="Warning" color="warning" */%}} - This is a warning. - {{%/* /alert */%}} - ``` + ```go-html-template + {{%/* alert title="Note" color="primary" */%}} + This is a note. + {{%/* /alert */%}} + ``` + + ```go-html-template + {{%/* alert title="Warning" color="warning" */%}} + This is a warning. + {{%/* /alert */%}} + ``` 5. If you add any commands to the content inline, surround the command with backticks (\` \`), like `ls -la` From fb0cf3c05691d880acce10bfaf8229f13cc378aa Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 10:31:07 +0300 Subject: [PATCH 5/8] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0c0c7c078..6fd6f09af9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -179,7 +179,7 @@ documentation contributions. [error message style guide]: architecture/style-guides/errors.md -[documentation style guide]: documentation/README.md#styl-guide-for-documentation +[documentation style guide]: documentation/README.md#style-guide-for-documentation [github help]: https://help.github.com/articles/about-pull-requests/ [google's open source community guidelines]: https://opensource.google.com/conduct/ From db30b23a45b16d5cc4a7925f64ebca504fc1e4fd Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 10:41:09 +0300 Subject: [PATCH 6/8] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- documentation/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index 41056427e9..b8271a91c4 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -62,11 +62,11 @@ git submodule update --init --recursive (\* \*) to mark any inline IP address, domain name, file name, file location, or similar. 7. Whenever possible, define the type of code for your code blocks - * \```shell for all shell blocks - * \```golang for all Go blocks - * \```yaml for all YAML blocks - * \```yang for all YANG blocks - * a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) + - \```shell for all shell blocks + - \```golang for all Go blocks + - \```yaml for all YAML blocks + - \```yang for all YANG blocks + - a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) 8. Links to other kpt doc pages should be absolute: From fa1770093976587cfe29b682d9a65daa35df8b8b Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 11:15:25 +0300 Subject: [PATCH 7/8] Fixing indentation of point 6 in style guide Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 --- documentation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/README.md b/documentation/README.md index b8271a91c4..ece7fe0d3b 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -59,7 +59,7 @@ git submodule update --init --recursive 5. If you add any commands to the content inline, surround the command with backticks (\` \`), like `ls -la` 6. Do not surround IP addresses, domain names, or any other identifiers with backticks. Use italics -(\* \*) to mark any inline IP address, domain name, file name, file location, or similar. + (\* \*) to mark any inline IP address, domain name, file name, file location, or similar. 7. Whenever possible, define the type of code for your code blocks - \```shell for all shell blocks From 09a58bf4645e7c315e3f039d14cbb54a0d46e6fb Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 11:22:52 +0300 Subject: [PATCH 8/8] Update README.md to improve code block formatting and fix license link path Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 --- documentation/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index ece7fe0d3b..c74de4a08b 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -62,10 +62,10 @@ git submodule update --init --recursive (\* \*) to mark any inline IP address, domain name, file name, file location, or similar. 7. Whenever possible, define the type of code for your code blocks - - \```shell for all shell blocks - - \```golang for all Go blocks - - \```yaml for all YAML blocks - - \```yang for all YANG blocks + - ```shell for all shell blocks + - ```golang for all Go blocks + - ```yaml for all YAML blocks + - ```yang for all YANG blocks - a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) @@ -104,4 +104,4 @@ git submodule update --init --recursive ## License -Licensed under the [Creative Commons Attribution 4.0 International license](LICENSE-documentation) +Licensed under the [Creative Commons Attribution 4.0 International license](../LICENSE-documentation)