Skip to content

Commit 0ef807c

Browse files
PeefyPeefy
authored
Merge pull request #374 from Peefy/docs-0.9
chore: add 0.9 documents
2 parents 4ff22d9 + 2d5a377 commit 0ef807c

File tree

336 files changed

+52228
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

336 files changed

+52228
-1
lines changed

‎VERSION

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.8
1+
0.9

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9.json

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
{
2+
"sidebar.user_docs.category.Get Started": {
3+
"message": "快速开始"
4+
},
5+
"sidebar.user_docs.category.Introduction": {
6+
"message": "简介"
7+
},
8+
"sidebar.user_docs.category.User Guide": {
9+
"message": "用户手册"
10+
},
11+
"sidebar.user_docs.guides.category.Automation": {
12+
"message": "自动化"
13+
},
14+
"sidebar.user_docs.category.Configuration": {
15+
"message": "配置"
16+
},
17+
"sidebar.user_docs.category.Data Integration": {
18+
"message": "数据集成"
19+
},
20+
"sidebar.user_docs.category.Package Management": {
21+
"message": "包管理工具"
22+
},
23+
"sidebar.user_docs.category.Package Management Tools": {
24+
"message": "包管理工具"
25+
},
26+
"sidebar.user_docs.category.How to": {
27+
"message": "如何使用"
28+
},
29+
"sidebar.user_docs.category.Schema Definition": {
30+
"message": "模型定义"
31+
},
32+
"sidebar.user_docs.category.Validation": {
33+
"message": "验证"
34+
},
35+
"sidebar.user_docs.category.Concepts": {
36+
"message": "核心概念"
37+
},
38+
"sidebar.user_docs.category.FAQ": {
39+
"message": "常见问答"
40+
},
41+
"sidebar.reference.category.Tutorial": {
42+
"message": "教程"
43+
},
44+
"sidebar.reference.category.Code Lab": {
45+
"message": "代码实验室"
46+
},
47+
"sidebar.reference.category.Spec": {
48+
"message": "语言规范"
49+
},
50+
"sidebar.reference.category.Errors and Warnings": {
51+
"message": "错误与警告"
52+
},
53+
"sidebar.reference.category.Types": {
54+
"message": "类型系统"
55+
},
56+
"sidebar.reference.category.System Package": {
57+
"message": "系统模块"
58+
},
59+
"sidebar.reference.category.Plugin System": {
60+
"message": "插件系统"
61+
},
62+
"sidebar.reference.category.Multi-Language": {
63+
"message": "多语言集成"
64+
},
65+
"sidebar.reference.category.Cheat Sheet": {
66+
"message": "备忘表"
67+
},
68+
"sidebar.reference.category.Package Management": {
69+
"message": "包管理工具"
70+
},
71+
"sidebar.reference.category.Command Reference": {
72+
"message": "命令参考"
73+
},
74+
"sidebar.reference.category.Advanced-Concepts": {
75+
"message": "进阶概念"
76+
},
77+
"sidebar.reference.category.Best-Practices": {
78+
"message": "最佳实践"
79+
},
80+
"sidebar.tools.category.Command Line Tools": {
81+
"message": "命令行工具"
82+
},
83+
"sidebar.tools.category.KCL Tools": {
84+
"message": "语言工具"
85+
},
86+
"sidebar.tools.category.Package Management Tools": {
87+
"message": "包管理工具"
88+
},
89+
"sidebar.tools.category.OpenAPI Tools": {
90+
"message": "OpenAPI 工具"
91+
},
92+
"sidebar.community.category.Community": {
93+
"message": "简介"
94+
},
95+
"sidebar.community.category.Types": {
96+
"message": "类型系统"
97+
},
98+
"sidebar.community.category.Contribution Guide": {
99+
"message": "贡献指南"
100+
},
101+
"sidebar.community.category.Release Policy": {
102+
"message": "发布策略"
103+
},
104+
"sidebar.docs.category.GitOps": {
105+
"message": "GitOps",
106+
"description": "The label for category GitOps in sidebar docs"
107+
},
108+
"sidebar.docs.category.CI Integration": {
109+
"message": "CI 集成",
110+
"description": "The label for category CI Integration in sidebar docs"
111+
},
112+
"sidebar.user_docs.category.GitOps": {
113+
"message": "GitOps",
114+
"description": "The label for category GitOps in sidebar user_docs"
115+
},
116+
"sidebar.user_docs.category.CI Integration": {
117+
"message": "CI 集成",
118+
"description": "The label for category CI Integration in sidebar user_docs"
119+
},
120+
"sidebar.docs.category.Mutate or Validate Kubernetes Manifests": {
121+
"message": "编辑或验证 Kubernetes 资源",
122+
"description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar docs"
123+
},
124+
"sidebar.user_docs.category.Mutate or Validate Kubernetes Manifests": {
125+
"message": "编辑或验证 Kubernetes 资源",
126+
"description": "The label for category Mutate or Validate Kubernetes Manifests in sidebar user_docs"
127+
},
128+
"sidebar.docs.category.Secret Management": {
129+
"message": "敏感信息管理",
130+
"description": "The label for category Secret Management in sidebar docs"
131+
},
132+
"sidebar.user_docs.category.Secret Management": {
133+
"message": "敏感信息管理",
134+
"description": "The label for category Secret Management in sidebar user_docs"
135+
}
136+
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "社区",
3+
"position": 5
4+
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/contribute/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "贡献指南",
3+
"position": 4
4+
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/contribute/contribute-code.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# 如何贡献代码?
6+
7+
欢迎参与 KCL 共建贡献完善代码、完善代码文档和测试，同时也欢迎通过 Issue 提供反馈。本文主要针对修改和完善已有的代码，如果是希望增加 KCL 语言特性请通过 KEP 流程提交。
8+
9+
## 1. 代码和注释中的错别字
10+
11+
如果只是修改代码和注释中的错别字，不涉及代码逻辑的调整，那么可以直接在 Github 克隆仓库后直接修改并提交 PR。需要注意的是尽量保持代码风格一致。
12+
13+
## 2. 如何贡献 KCL 代码
14+
15+
- 先确保本地测试环境正常
16+
- 修改代码并补充测试
17+
- 本地测试通过后提交 PR
18+
19+
## 3. 如何贡献 VS Code 插件代码
20+
21+
请参考 VS Code 插件仓库的相关文档
22+
23+
## 4. 开发流程相关代码
24+
25+
欢迎通过 Issue 和讨论组讨论。

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/contribute/contribute-docs.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# 如何贡献文档?
6+
7+
本文主要针对已有的文档做局部修改。如果是投稿博客文章、添加新的文档或者调整文档目录结构请先联系团队成员。
8+
9+
KCL 文档分为用户指南、开发文档、内部文档、参考手册和博客文章等，他们的区别如下：
10+
11+
- 用户指南：对应使用文档，是让用户以最小的代价快速使用 KCL 工具完整工作，不要涉及太多的内部原理和实现
12+
- 开发文档：内部是怎么实现的，主要针对希望了解 KCL 原理和参与贡献和开发的同学
13+
- 内部文档：针对企业用户的一些内部场景定制的文档
14+
- 参考手册：KCL 语言、工具和 IDE 等全部特性的文档，内容覆盖最广但比较琐碎
15+
- 博客文章：没有特别的限制，可以是针对某些具体的场景、某些技术点或者是整体发展展望等分享文章
16+
17+
在贡献不同类型的文档时，最好能够结合上面的定位对不同的内容做一些适当的裁剪，给读者最佳体验。
18+
19+
## 1. 基本规范
20+
21+
- 除标题外，内部小标题尽量带编号，便于阅读
22+
- 工具自动输出的文档需要由到源代码的链接，小标题可以不带编号
23+
- 尽量不要贴大段的代码（30行以内），代码最好给出文字解释和对应的参考链接
24+
- 有图有真相，但是不推荐过度复杂的架构图
25+
- 内部链接：采用 `/docs/user_docs/getting-started/intro` 绝对路径形式
26+
27+
**标点和空格**
28+
29+
- 在中文的文档中优先使用中文的标点
30+
- 中文和英文之间需要增加 1 个空格
31+
- 中文和数字之间需要增加 1 个空格
32+
- 中文使用全角标点，标点前后均不添加空格
33+
- 英文内容使用半角标点，标点后面加 1 个空格
34+
- 链接前后需要保留一个空格，但是段落开头和中文全角标点附近不用添加空格。
35+
36+
**图片和资源文件名**
37+
38+
- 文件名和目录名只能用数字、英文字母、下划线 `_` 和减号 `-` 组成
39+
- 当前文档的图片放在当前目录的 images 目录下
40+
- 矢量图片可以通过 [drawio 离线版](https://github.com/jgraph/drawio-desktop/releases) 绘制（并同时提交源文件），以 200% 分辨率导出 png 格式图片
41+
42+
## 2. 使用文档内容的基本模式
43+
44+
每个使用文档可以看作是一个相对完整的分享或博客文章（参考手册不再此类）。使用文档遵循以下模式组织内容：
45+
46+
1. 概览：本文希望解决什么问题，达到什么效果，可以先放最终效果截图
47+
1. 依赖的环境：需要安装什么工具，并给出相关链接
48+
1. 引入本文构建资源的关系图或架构图
49+
- 需要用到的 Konfig 模型，给出模型参考页面链接，以及对应的上游原始模型的文档链接
50+
1. 具体的操作步骤
51+
- 尽量确保最小化代码，甚至可以刻意隐藏一些干扰代码，同时给出完整代码对应的链接
52+
- 列出每个步骤命令的概要输出信息，并配以文字描述
53+
1. 给出测试方式
54+
- 尽量采用社区通用的方式（比如kube、curl命令、或浏览器）测试
55+
- 给出测试结果的截图（和开头呼应）
56+
1. 总结和展望
57+
- 简单回顾当前操作的流程，以及一些可以展开的地方（可以给出一些链接）
58+
59+
## 3. 测试和提交 PR
60+
61+
先克隆文档仓库，本地通过 `npm run start` 和 `npm run build` 命令测试查看效果，确保可以正常浏览后提交 PR 即可。

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/contribute/contribute.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# 贡献指南

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/contribute/git-guideline.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Git 提交指南
2+
3+
本文介绍了 Git 提交变更时需要注意的事项，如果拒绝接受本文的内容会导致提交的变更无法被接受。
4+
5+
## 1. 关于 issue
6+
7+
在提交一个 issue 之前，请先查阅已经关闭的 issue ，也许在关闭的 issue 中已经存在合适的解决方案。
8+
9+
如果没有找到合适的方案，我们提供了4种模版在创建 issue 的时候使用。
10+
11+
- Bug Report : 发现了一个 Bug，可以通过 Bug Report 模版创建 issue 与我们联系。
12+
- Enhancement : 开发者对工具进行了增强，可以通过 Enhancement 模版创建 issue 来介绍增加的内容。
13+
- Feature Request : 在使用的过程中想要为工具增加某些新的特性或者功能，可以通过 Feature Request 模版创建 issue 来描述新特性。
14+
- Ask a Question : 如果有任何的疑问，可以通过 Ask a Question 模版来创建一个 issue 与我们联系。
15+
16+
在选择合适的模版后，只需要填写模版上的要求填写的内容即可。如果在创建 issue 的时候发现没有模版，或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。
17+
18+
## 2. 关于 Git 分支
19+
20+
要向 kcl-lang 贡献代码，您必须拥有一个 GitHub 帐户，以便您可以将代码推送到您自己的分支并创建拉取请求。我们推荐参考 [Angular 规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) 为您自己的分支命名。
21+
推荐的格式如下：
22+
23+
```
24+
{type}-{a_short_description}
25+
```
26+
27+
分支名称主要包括两个字段，并通过 “-” 分割。其中：
28+
29+
- {type} : 当前分支内容的类型。
30+
- {a_short_description}: 一个简短的描述，介绍这个分支的主要内容。
31+
32+
e.g. 张三首先 Fork 仓库到自己账户下，然后创建对应名称 `zhangsan:fix-output-fmt-bug` 的分支（冒号之前是张三的账号），用于修复输出格式化 bug。
33+
34+
## 3. 关于 Git Commit
35+
36+
我们参考 [Commitizen](https://github.com/commitizen/cz-cli) 书写 Commit Message。
37+
38+
```
39+
注: 如果直接使用 Commitizen 生成 Commit Message，需要注意因为 Commitizen
40+
是开发人员管理 commit 的工具，与项目本身无关联，因此由 Commitizen 生成的中间产物
41+
(如: node_modules 文件目录)可能没有在项目 .gitignore 文件中。
42+
43+
您可以 git add {filename} 选择要提交的文件而忽视中间产物。
44+
或者您可以向 .gitignore 文件中添加如下内容而自动忽视中间产物：
45+
# commitizen
46+
package.json
47+
package-lock.json
48+
node_modules/*
49+
```
50+
51+
如果手动编写 Commit Message，我们也建议采用 [Commitizen](https://github.com/commitizen/cz-cli) 的 commit message 格式。
52+
53+
```
54+
{type} ( {component_or_file} ) {a_short_description}
55+
{a_longer_description}
56+
BREAKING CHANGE: {breaking_change_description}.
57+
{linked issue}
58+
```
59+
60+
其中主要包括6个字段：
61+
62+
- {type} : 当前 commit 对应的分支的类型。
63+
- {component_or_file}: 当前 commit 改动的模块或者文件的名称。
64+
- {a_short_description}: 简短的描述介绍 commit 中的内容。
65+
- {a_longer_description}: 详细的描述用来介绍 commit 中的内容。
66+
- {breaking_change_description}: 如果 commit 中包含破环兼容性的改动，需要对兼容性改动产生的影响进行介绍。
67+
- {linked issue}: 与当前这个 commit 关联的 issue。
68+
69+
其中 {breaking_change_description} 和 {linked issue} 如果 commit 中不包含破坏兼容性的改动和关联的 issue，可以省略。
70+
71+
e.g. 张三在分支 `zhangsan:fix-output-fmt-bug` 中创建的 commit。
72+
73+
```
74+
75+
fix(kcl-printer): fix an output format bug in kcl-printer
76+
77+
There is an output format bug in kcl-printer because ...,
78+
So, The calling of method "XXX" is replaced by "HHHH"...,
79+
...
80+
81+
-- 如果没有破坏兼容性的改动和关联的 issue 可以省略下面内容。
82+
83+
BREAKING CHANGE: This change maybe cause .......
84+
85+
fix #123
86+
87+
```
88+
89+
## 4. 关于 pull request
90+
91+
在提交一个 PR 之前，可能需要优先考虑以下几个问题:
92+
93+
- 请先查阅已经关闭的 PR ，也许在已经关闭的 PR 中，可能存在已经完成的解决方案。
94+
- 我们建议在提交变更之前，提交一个对应的 issue 描述变更中将要解决的问题，并将变更对应的 PR 与 issue 关联。
95+
- 在向我们提交 PR 之后，请签署 [Contributor License Agreement (CLA)](#cla) ，如果拒绝签署，我们将无法接受 PR。
96+
- 请确保每次改动都创建了一个新的分支，并根据上文中提到的规范为分支命名。
97+
- 一次 PR 请不要超过两个 commit ，请将多余的 commit 通过 squash 压缩，并根据上文中提到的规范，编写 commit message 。
98+
- 我们提供了 [PR 模版](https://github.com/kcl-lang/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md)，只需要添加模版中要求的内容即可，如果在创建PR时发现没有模版或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。
99+
100+
我们建议PR的标题与分支名、commit message 风格保持一致：
101+
102+
```
103+
{type} ( {component_name_or_file_name} ) :{a_short_description}
104+
```
105+
106+
e.g. 张三为分支`fix/zhangsan/fix_output_fmt_bug`创建的PR名称。
107+
108+
```
109+
fix(kcl-printer): fix an output format bug in kcl-printer.
110+
```
111+
112+
## 5. 目前 type 支持的类型
113+
114+
参考[Angular 规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)，type 支持类型的类型如下:
115+
116+
```
117+
- feat: -- 添加了新的功能特性。
118+
- fix: -- 进行了 Bug 的修复。
119+
- docs: -- 进行了文档部分的修改。
120+
- style: -- 对代码格式的修改，并不影响代码的功能，如：删除多余空格，代码缩进等。
121+
- refactor: -- 在不改变代码功能的基础上对代码进行了的重构。
122+
- perf: -- 对代码进行了性能优化。
123+
- test: -- 添加或者调整已有的测试用例。
124+
- build: -- 对构建系统或者外部依赖库进行了调整。
125+
- ci: -- 调整了 CI 的配置文件或者脚本。
126+
- chore: -- 对源代码和测试文件之外其他部分的调整。
127+
- revert: -- 对 commit 进行回滚。
128+
```
129+
130+
## <a name="cla"></a> 6. Contributor License Agreement (CLA)
131+
132+
在第一次向我们提交 PR 之后，在 PR 中的 CLA 检查将会失败并提示签署 CLA。您可以通过自己的账户之间在 PR 回复 "I have read the CLA Document and I hereby sign the CLA" 表示同意签署 CLA，然后手动重启失败的 CLA 检查 Action 即可。当 PR 被成功合并之后将会被锁定不能再修改。

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/intro/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "简介",
3+
"position": 1
4+
}

‎i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/community/intro/intro.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# 社区
6+
7+
欢迎来到 KCL 开源社区，每个人的参与都是所有开源项目健康成长的动力！有很多方法可以参与开源。每个人都可以通过提交PR（Pull Request）来创建问题或修复 bug、改进文档或修改代码，
8+
9+
可以查看[社区](https://github.com/kcl-lang/community)并加入我们。

0 commit comments

Comments
 (0)