docs: refactor docs about development

Signed-off-by: Bird <aflybird0@gmail.com>

docs/development/commands/develop.md → docs/commands/develop.md

@@ -10,7 +10,7 @@
 
 ## 2 Full Process Guide
 
-A detailed guide to the plugin development process can be found in [creating a plugin](../creating-a-plugin.md).
+A detailed guide to the plugin development process can be found in [creating a plugin](../development/dev/creating-a-plugin.md).
 
 ## 3 Flags
 

docs/development/commands/develop.zh.md → docs/commands/develop.zh.md

@@ -9,7 +9,7 @@
 
 ## 2 完整插件开发指南
 
-插件开发的详细指南可以在[创建一个插件](../creating-a-plugin.zh.md)找到。
+插件开发的详细指南可以在[创建一个插件](../development/dev/creating-a-plugin.zh.md)找到。
 
 ## 3 命令行参数
 

docs/contributing_guide.md

@@ -41,7 +41,7 @@ Absolutely everyone is welcome to come to any of our meetings. You never need an
 
 We have good first issues for new contributors and help wanted issues suitable for any contributor.
 
-- [good first issue](https://github.com/devstream-io/devstream/labels/good%20first%20issue) has extra information to help you make your first contribution. If you are new to DevStream (or even new to open-source,) this is a good place to get yourself started. For more information, see the [good first issues doc](./development/good-first-issues.md).
+- [good first issue](https://github.com/devstream-io/devstream/labels/good%20first%20issue) has extra information to help you make your first contribution. If you are new to DevStream (or even new to open-source,) this is a good place to get yourself started. For more information, see the [good first issues doc](development/git-workflow/good-first-issues.md).
 - [help wanted](https://github.com/devstream-io/devstream/labels/help%20wanted) are issues suitable for someone who isn't a core maintainer and is good to move onto after your "good first issue."
 - Sometimes there won’t be any issues with these labels. That’s ok! There is likely still something for you to work on. If you want to contribute but you don’t know where to start or can't find a suitable issue, you can reach out to us on our [Slack channel](https://cloud-native.slack.com/archives/C03LA2B8K0A) and ask for an issue to work on.
 
@@ -72,17 +72,25 @@ The unwritten rules (heck, we are writing them anyways) for PRs, contributors, a
 - Currently, we don't release regularly, so there isn't any guarantee about when your PR will be included in the next release. However, we are trying our best to make releases as frequent as possible.
 - As an encouragement to contributors, it's fine to close an issue or merge a PR even if the originally designed features aren't 100% implemented. In cases like this, please encourage contributors to create a follow-up issue and PR to further implement that. Do not make the PR process last too long because it might discourage contributors.
 
-## Development Environment Setup
+For more documentation on GitHub collaboration, see the [GitHub Collaboration Process Guidelines](./development/git-workflow/git-workflow.md).
 
-- linter: [golangci-lint](https://github.com/golangci/golangci-lint)
-- recommended IDE: [Visual Studio Code](https://code.visualstudio.com/), [GoLand](https://www.jetbrains.com/go/).
-- [docs](https://docs.devstream.io/en/latest/)
-- [quick start](./quickstart.md)
-- Get the source code: https://github.com/devstream-io/devstream
-- [Build the source code](./development/build.md)
-- [Test the source code, unit](./development/test.md)
-- TODO: Test the source code, integration/end-to-end
-- TODO: Generate and preview the documentation locally
+## Development
+
+- Recommended IDEs: [Visual Studio Code](https://code.visualstudio.com/), [GoLand](https://www.jetbrains.com/go/)
+- [Development Environment Setup](./development/dev/dev-env-setup.md)
+- [Code linter](./development/dev/lint.md)
+- [Build the source code](./development/dev/build.md)
+- [Test the source code: unit test, e2e test](./development/dev/test.md)
+
+## DevStream Architecture
+
+- [overall architecture](development/devstream/architecture.md)
+- [Project Organization](development/devstream/project-layout.md)
+
+## Documentation Contribution
+
+- [Create documentation for DevStream](./development/docs-contribution/mkdocs.md)
+- [Document translation](./development/docs-contribution/translation.md)
 
 ## Sign Your Commits
 
@@ -108,7 +116,7 @@ When you submit your pull request, or you push new commits to it, our automated
 
 - Lint your code. Although this will be checked by our CI, linting it yourself locally first before creating a PR will save you some time and effort.
 - Build/test your code. Same as above.
-- Double-check your commit messages. See if they meet the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/). Again, this will also be validated by our CI, but checking it yourself beforehand will speed things up drastically.
+- Double-check your commit messages. More details in the [commit message guidelines](./development/git-workflow/commit-messages.md).
 
 ## Maintainer Team at Merico
 

docs/contributing_guide.zh.md

@@ -19,7 +19,7 @@
 - Bug 修复
 - 文档
 - Issue 分类、发起、回复、管理、维护等（Issue Triage）
-- 在 微信群、Sack、邮件列表解答问题
+- 在 微信群、Slack、邮件列表解答问题
 - 网站页面设计
 - 在各种媒体、博客文章宣传 DevStream
 - 发版管理
@@ -38,12 +38,12 @@ DevStream 真诚地欢迎每一个人参与我们的会议，不需要被邀请
 ## 寻找 Issue
 你可以在 Issue 列表找到这样两个标签： `good first issue` 表示仅向新贡献者开放，`help wanted` 适合于所有贡献者。
 
-- [good first issue](https://github.com/devstream-io/devstream/labels/good%20first%20issue) 含有更多的描述信息与指导，往往只涉及一小部分，完成它不需要你熟悉整个项目。如果你是第一次参与 DevStream（甚至是第一次参与开源），非常推荐你从 good first issue 开始共建之旅。更多信息，请参阅 [good first issue 文档](./development/good-first-issues.zh.md)。
+- [good first issue](https://github.com/devstream-io/devstream/labels/good%20first%20issue) 含有更多的描述信息与指导，往往只涉及一小部分，完成它不需要你熟悉整个项目。如果你是第一次参与 DevStream（甚至是第一次参与开源），非常推荐你从 good first issue 开始共建之旅。更多信息，请参阅 [good first issue 文档](development/git-workflow/good-first-issues.zh.md)。
 - [help wanted](https://github.com/devstream-io/devstream/labels/help%20wanted) 指引了你在完成了 good first issue 后，适合继续贡献的地方。带有这个标签的 issue，除了核心贡献者外的任何人都可参与。
 - 你不需要拘泥于带有这两个标签的 issue，其他任何你感兴趣的 issue，都可以直接参与，无论是方案修改建议、讨论与回复、还是代码。
 - 有时 good first issue 或 help wanted 因为社区过于热情导致暂时没有空余，只要你愿意，你仍可以参与贡献！直接在 [Slack](https://join.slack.com/t/devstream-io/shared_invite/zt-16tb0iwzr-krcFGYRN7~Vv1suGZjdv4) 或 [微信群](https://github.com/devstream-io/devstream/main/docs/images/wechat-group-qr-code.png) 联系我们，告诉我们你愿意参与！
 
-若你想负责某个 issue，请在 issue 内留下评论，例如："I want to work on this"。
+如果你对某个 issue 有兴趣，想完成对应内容，请在 issue 内留下评论，例如："I want to work on this"。
 
 ## 寻求帮助
 在贡献时，向我们提问的最好的方式如下：
@@ -69,18 +69,28 @@ DevStream 真诚地欢迎每一个人参与我们的会议，不需要被邀请
 - 目前，我们不会定期发布，因此无法保证你的 PR 何时包含在下一个版本中。但是，我们正在尽最大努力使发布尽可能频繁。
 - 为了鼓励贡献者，你可以在未100%完成原有设计的情况下，完成相应的任务，即关闭 issue 与合并 PR。在这种情况下，你可以再创建个新的 issue，并提交个新的 PR 来完成之前遗漏的工作。我们不希望你在一个 PR 上耗时太久，这会打击你的兴趣。
 
-## 开发环境搭建
-- 代码格式检查：[golangci-lint](https://github.com/golangci/golangci-lint)
+更多关于 GitHub 协作的文档，可参考 [GitHub 协作流程指引](./development/git-workflow/git-workflow.md)。
+
+## 开发
+
 - 推荐的 IDE：[Visual Studio Code](https://code.visualstudio.com/), [GoLand](https://www.jetbrains.com/go/)
-- [文档](https://docs.devstream.io/en/latest/index.zh/)
-- [快速开始](https://docs.devstream.io/en/latest/quickstart.zh/)
-- [源码](https://github.com/devstream-io/devstream)
-- [源码构建](https://docs.devstream.io/en/latest/development/build.zh/)
-- [代码测试：单元测试(unit test)、端到端测试(e2e test)](https://docs.devstream.io/en/latest/development/test.zh/)
-- TODO: 源码测试, 集成/端到端测试
-- TODO: 生成本地文档预览
+- [开发环境搭建](./development/dev/dev-env-setup.zh.md)
+- [代码格式检查](./development/dev/lint.zh.md)
+- [源码构建](./development/dev/build.zh.md)
+- [代码测试：单元测试(unit test)、端到端测试(e2e test)](./development/dev/test.zh.md)
+
+## 架构解读
+
+- [整体架构](development/devstream/architecture.zh.md)
+- [项目组织结构](development/devstream/project-layout.zh.md)
+
+## 文档类贡献
+
+- [为DevStream创建文档](./development/docs-contribution/mkdocs.zh.md)
+- [文档翻译](./development/docs-contribution/translation.zh.md)
 
 ## 代码提交署名（Sign Off）
+
 授权与认证（licensing) 对于开源项目非常重要，它确保了软件能基于作者提供的条款继续运作。我们需要你在贡献代码的时候署名你的提交，[Developer Certificate of Origin (DCO)](https://developercertificate.org/) 是一种认证你编写了此段代码，并表明你持有这段代码的方式。
 
 你可以通过在提交信息（Git Commit Message）中附加这段信息。注意，你的署名必须与 Git 的用户名和邮箱对应。
@@ -103,7 +113,7 @@ Git 有一个 `-s` 的命令行选项可以帮助你自动署名:
 
 - 检查代码格式问题([golangci-lint](https://github.com/golangci/golangci-lint)): 虽然我们的 CI 会在提交代码时自动运行 lint，但在本地先执行 lint 确保无误后再提交能节省你更多的精力与时间。
 - 构建/测试 代码，同上。
-- 仔细检查你的提交信息（Commit Message）：确认它们符合 [约定式提交](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 规范。同样的，CI 也会执行这一检查，但若你在提交代码前先行检查能加快 PR 合并速度。
+- 仔细检查你的提交信息（Commit Message）：详见 [提交信息规范](./development/git-workflow/commit-messages.zh.md)。
 
 ## Maintainer 团队
 

docs/development/creating-a-plugin.md → docs/development/dev/creating-a-plugin.md

@@ -24,7 +24,7 @@ Although dtm is automagic, but it can’t read your mind. I’m afraid that you
 
 Please fill in the main logic of the plugin here.
 
-You can check out our [Standard Go Project Layout](project-layout.md) document for detailed instruction on the project layout.
+You can check out our [Standard Go Project Layout](../devstream/project-layout.md) document for detailed instruction on the project layout.
 
 ## 2 Interfaces
 

docs/development/creating-a-plugin.zh.md → docs/development/dev/creating-a-plugin.zh.md

@@ -24,7 +24,7 @@
 
 请在这里编写插件的主要逻辑。
 
-可以查看我们的[Standard Go Project Layout](project-layout.zh.md)文件，了解关于项目布局的详细说明。
+可以查看我们的[Standard Go Project Layout](../devstream/project-layout.zh.md)文件，了解关于项目布局的详细说明。
 
 ## 2 接口
 

docs/development/dev-env-setup.md → docs/development/dev/dev-env-setup.md

@@ -6,15 +6,15 @@ OK. So you want to get started with Golang/Kubernetes development. You've come t
 
 [Head to the official website](https://go.dev/) and click the "Download" button:
 
-![](../images/golang-install.png)
+![](../../images/golang-install.png)
 
 Make sure you select the correct package according to your operating system and processor:
 
-![](../images/golang-download.png)
+![](../../images/golang-download.png)
 
 For Apple macOS users, click the apple logo in the menu bar, and choose "About This Mac" to check your chip:
 
-![](../images/about-this-mac.png)
+![](../../images/about-this-mac.png)
 
 ---
 
@@ -26,7 +26,7 @@ The easiest way to run a Kubernetes cluster locally is to run it in a Docker con
 
 [Head to the official website](https://www.docker.com/) and click the download button:
 
-![](../images/docker-install.png)
+![](../../images/docker-install.png)
 
 Again, please pay attention to the operating system and processor options. For Apple M1 mac users, choose the "Apple Chip" option. To check what processor you have, see the previous section in "About This Mac".
 
@@ -42,15 +42,15 @@ _Note: there are other tools which can install a local K8s, such as `kind`, etc.
 
 First, go to the [official website of minikube](https://minikube.sigs.k8s.io/docs/start/), choose the right OS and architecture (again,) and download/install:
 
-![](../images/minikube-install.png)
+![](../../images/minikube-install.png)
 
 Alternatively, if you are using [Homebrew](https://brew.sh/) (if you don't know what it is, ignore this line,) you can simply run `brew install minikube`.
 
 ### 2.3 Install `kubectl`
 
 Go to [Kubernetes' official documentation website](https://kubernetes.io/docs/tasks/tools/) and follow the guide to install kubectl. Choose your operating system:
 
-![](../images/kubectl-install.png)
+![](../../images/kubectl-install.png)
 
 Again, for macOS users, if you are using Homebrew package manager, you can install kubectl with Homebrew:
 
@@ -116,4 +116,4 @@ For example, you can try a local build:
 make build -j10 VERSION=0.8.0
 ```
 
-Or, maybe you would like to have a go with it first? Check our [quickstart guide](../quickstart.md). Happy hacking!
+Or, maybe you would like to have a go with it first? Check our [quickstart guide](../../quickstart.md). Happy hacking!

docs/development/dev-env-setup.zh.md → docs/development/dev/dev-env-setup.zh.md

@@ -6,15 +6,15 @@
 
 [前往Golang官网](https://go.dev/)并点击“下载”按钮：
 
-![](../images/golang-install.png)
+![](../../images/golang-install.png)
 
 根据你的操作系统和处理器来选择正确的软件包版本：
 
-![](../images/golang-download.png)
+![](../../images/golang-download.png)
 
 对于Apple macOS用户，点击菜单栏中的苹果标志，然后选择“关于本机”以查看您的芯片：
 
-![](../images/about-this-mac.png)
+![](../../images/about-this-mac.png)
 
 ---
 
@@ -26,7 +26,7 @@
 
 [前往Docker官网](https://www.docker.com/)点击下载按钮：
 
-![](../images/docker-install.png)
+![](../../images/docker-install.png)
 
 同样请注意操作系统和处理器选项。对于Apple M1 mac用户，选择“Apple Chip”选项。如果想确认你的处理器是Apple还是Intel，请参阅上一节中的“关于本机”部分。
 
@@ -42,15 +42,15 @@ _注意：其实有很多种可以安装本地K8s的工具，如`kind`等；在
 
 首先，访问[minikube官网](https://minikube.sigs.k8s.io/docs/start/)，选择正确的操作系统和架构，并下载/安装：
 
-![](../images/minikube-install.png)
+![](../../images/minikube-install.png)
 
 或者，如果你在用[Homebrew](https://brew.sh/)的话（如果你不知道它是啥，请忽略）你可以通过运行`brew install minikube`来安装。
 
 ### 2.3 安装`kubectl`
 
 前往[Kubernetes的官方文档站点](https://kubernetes.io/docs/tasks/tools/)然后按照指南来安装kubectl。选择您的操作系统：
 
-![](../images/kubectl-install.png)
+![](../../images/kubectl-install.png)
 
 需要再次强调的是，对于macOS用户，如果你用Homebrew包管理器，那么你可以用brew装kubectl：
 
@@ -116,6 +116,6 @@ git clone https://github.com/devstream-io/devstream.git
 make build -j10 VERSION=0.8.0
 ```
 
-或者可能你想先试用一下DevStream？没问题，参考我们的[快速开始](../quickstart.zh.md)文档！
+或者可能你想先试用一下DevStream？没问题，参考我们的[快速开始](../../quickstart.zh.md)文档！
 
 Happy hacking!

docs/development/lint.zh.md → docs/development/dev/lint.zh.md

@@ -1,6 +1,5 @@
 # 代码检查
 
-
 项目使用Go 的代码检查工具集`golangci-lint` ([official website](https://golangci-lint.run/), [GitHub](https://github.com/golangci/golangci-lint)) 进行代码格式检查。
 
 也支持与 Github 工作流集成。

docs/development/architecture.md → docs/development/devstream/architecture.md

@@ -6,7 +6,7 @@ This document summarizes the main components of DevStream and how data flows bet
 
 The following diagram shows an approximation of how DevStream executes a user command:
 
-![DevStream Architecture Diagram](../images/architecture-overview.png)
+![DevStream Architecture Diagram](../../images/architecture-overview.png)
 
 There are three major parts:
 
@@ -64,4 +64,4 @@ A _plugin_ implements the aforementioned, predefined interfaces.
 
 It executes operations like `Create`, `Read`, `Update`, and `Delete`.
 
-To develop a new plugin, see [creating a plugin](./creating-a-plugin.md).
+To develop a new plugin, see [creating a plugin](../dev/creating-a-plugin.md).

docs/development/architecture.zh.md → docs/development/devstream/architecture.zh.md

@@ -6,7 +6,7 @@
 
 下图展示了DevStream是如何执行一个用户命令的。
 
-![DevStream架构图](../images/architecture-overview.png)
+![DevStream架构图](../../images/architecture-overview.png)
 
 DevStream主要由三大块组成：
 
@@ -62,4 +62,4 @@ Plugin engine通过调用以下模块来实现目标：
 
 它执行的包括"创建"、"读取"、"更新"和"删除"等操作。
 
-要开发一个新的插件，请参阅[创建一个插件](./creating-a-plugin.zh.md)。
+要开发一个新的插件，请参阅[创建一个插件](../dev/creating-a-plugin.zh.md)。

docs/development/mkdocs.zh.md → docs/development/docs-contribution/mkdocs.zh.md

@@ -1,4 +1,4 @@
-# 为DevStream创建中文文档
+# 为DevStream创建文档
 
 ## 背景
 

docs/development/commit-messages.zh.md → docs/development/git-workflow/commit-messages.zh.md

@@ -1,4 +1,4 @@
-# Commit 信息
+# Commit 信息规范
 我们尽最大的努力遵守[conventional commits](https://www.conventionalcommits.org/zh-hans/v1.0.0/#概述)规范。
 
 TL;DR：提交信息应当结构如下：

docs/development/development-workflow.md → docs/development/git-workflow/git-workflow.md

@@ -1,6 +1,6 @@
-# Development Workflow
+# Development Workflow with Git
 
-This document shows the workflow of how to develop DevStream.
+This document shows the workflow of how to develop DevStream with Git.
 
 ## Step 1 - Fork the repo
 

docs/development/development-workflow.zh.md → docs/development/git-workflow/git-workflow.zh.md

@@ -1,6 +1,6 @@
-# 开发工作流
+# Git协作工作流
 
-这篇文档是关于如何参与DevStream开发的流程。
+这篇文档是关于如何通过GitHub参与DevStream开发的流程。
 
 ## 第一步 - Fork 仓库
 1. 打开项目仓库： https://github.com/devstream-io/devstream ；
@@ -17,7 +17,7 @@ export PROJECT="devstream"
 export ORG="devstream-io"
 ```
 
-2. Clone仓库到你本地
+2. Clone 仓库到你本地
 ```sh
 mkdir -p ${WORKING_PATH}
 cd ${WORKING_PATH}
@@ -69,3 +69,7 @@ git push -f origin feat-xxx
 ```
 
 然后你就可以在GitHub上创建一个`pr`。
+
+## 附录
+
+也欢迎阅读我们的博客-[如何参与开源项目 - 细说 GitHub 上的 PR 全过程](https://blog.devstream.io/posts/open-a-pr-in-github/)，了解更多 GitHub 协作流程，如解决冲突等。

docs/development/good-first-issues.md → docs/development/git-workflow/good-first-issues.md

@@ -10,11 +10,11 @@ Items marked with the “good first issue” label are intended for _first-time_
 
 ### For Contributors
 
-After a contributor has completed one (or two) "good first issue" items, it's recommended to move on to the "[help wanted](../contributing_guide.md#find-an-issue)" label, saving the remaining "good first issue" items for other new contributors.
+After a contributor has completed one (or two) "good first issue" items, it's recommended to move on to the "[help wanted](../../contributing_guide.md#find-an-issue)" label, saving the remaining "good first issue" items for other new contributors.
 
 ### For Reviewers
 
-- Keep an eye on pull requests for "good first issue" and guide the contributors through the [pull request process](../contributing_guide.md#pull-request-lifecycle).
+- Keep an eye on pull requests for "good first issue" and guide the contributors through the [pull request process](../../contributing_guide.md#pull-request-lifecycle).
 - Let them know what the next step is. For example:
     - move on to another good first issue if they are not completely confident yet
     - find "help wanted" issues