Merge pull request #469 from Startrekzky/dashboard

docs: add Chinese READMEs

Author: klesh

CONTRIBUTING-zh-CN.md

@@ -0,0 +1,61 @@
+# 为 Dev Lake 做贡献
+
+👍🎉 首先，感谢你付出的时间！ 🎉👍
+
+以下是一套为 Dev Lake 做贡献的准则。这些主要是指导方针，而非规则。又任何修改建议，请根据个人判断提 PR 即可。
+
+
+## 我如何贡献？
+
+1. 通过填写所需的 issue 模板并将新问题标记为 "bug" 来报告bug
+
+2. 建议增强功能
+
+如果你打算更改公共 API，或者对实现进行任何非微不足道的改变，我们建议提交一个 issue。这可以确保在你投入大量精力之前，我们已经就方案达成一致。
+
+如果你只是修复一个bug，马上提交一个 pull request 也是可以的，但我们仍然建议提交一个 issue，详细说明你要修复的内容。这对于我们“不接受一个特定的修复，但又想跟踪这个问题”的情况下是很有帮助的。
+
+
+## 维护者团队 @ Merico
+
+Dev Lake由Merico的一群工程师维护，由[@hezyin]（https://github.com/hezyin）领导。我们的目标是实现 24 小时内回复问题的 SLA
+
+## 风格指南
+
+### Git Commit Message
+
+我们遵循此规范：[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+
+#### Commit 工具
+
+我们使用 https://github.com/lintingzhen/commitizen-go 来提交Commit
+
+```sh
+make commit
+```
+
+```
+> lake@1.0.0 commit /home/code/merico-dev/lake
+> cz
+
+cz-cli@4.2.4, cz-conventional-changelog@3.3.0
+
+? Select the type of change that you're committing: (Use arrow keys)
+> feat:     A new feature
+  fix:      A bug fix
+  docs:     Documentation only changes
+  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+  refactor: A code change that neither fixes a bug nor adds a feature
+  perf:     A code change that improves performance
+  test:     Adding missing tests or correcting existing tests
+(Move up and down to reveal more choices)
+? What is the scope of this change (e.g. component or file name): (press enter to skip)
+? Write a short, imperative tense description of the change (max 93 chars):
+ (23) add commit message tool
+? Provide a longer description of the change: (press enter to skip)
+
+? Are there any breaking changes? No
+? Does this change affect any open issues? No
+[chore/commit_message dc34f57] chore: add commit message tool
+ 5 files changed, 585 insertions(+), 4 deletions(-)
+```

README-zh-CN.md

@@ -0,0 +1,186 @@
+<br />
+<img src="https://user-images.githubusercontent.com/3789273/128085813-92845abd-7c26-4fa2-9f98-928ce2246616.png" width="120px">
+
+# Dev Lake
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat&logo=github&color=2370ff&labelColor=454545)](http://makeapullrequest.com)
+[![Discord](https://img.shields.io/discord/844603288082186240.svg?style=flat?label=&logo=discord&logoColor=ffffff&color=747df7&labelColor=454545)](https://discord.gg/83rDG6ydVZ)
+![badge](https://github.com/merico-dev/lake/actions/workflows/main.yml/badge.svg)
+
+
+
+| [English](README.md) | [中文](README-zh-CN.md) |
+| --- | --- |
+
+<br>
+
+### 什么是 Dev Lake？
+
+Dev Lake 是一个研发效能分析平台，它通过对软件开发生命周期（SDLC）中产生的数据进行 _**整合、分析和可视化**_ ，提升研发效能。
+
+<img src="https://user-images.githubusercontent.com/2908155/130271622-827c4ffa-d812-4843-b09d-ea1338b7e6e5.png" width="100%" alt="Dev Lake Grafana Dashboard" />
+
+### 为什么选择 Dev Lake？
+
+1. 支持各种数据源(<a href="https://gitlab.com/" target="_blank">Gitlab</a>, <a href="https://www.atlassian.com/software/jira" target="_blank">Jira</a>)，而且还在不断增加
+2.  相关的、可定制的数据指标，可随时作为可视化图表查看
+3.  利用 <a href="https://grafana.com/" target="_blank">Grafana</a> 轻松构建和查看新的图表和仪表盘
+4.  易于通过 <a href="https://docs.docker.com/desktop/" target="_blank">Docker</a> 进行设置
+5.  可扩展的插件系统，可添加您自己的数据采集器
+6.  专为处理企业规模的数据而设计
+
+## 内容
+
+目录 | 描述 | 文档链接
+:------------ | :------------- | :-------------
+数据源 | 链接到具体的插件使用和细节 | [查看本节](#data-source-plugins)
+用户设置 | 以用户身份运行项目的步骤 | [查看本节](#user-setup) 
+开发者设置 | 如何设置开发环境 | [查看本节](#dev-setup)
+测试 | 运行测试的命令 | [查看本节](#tests)
+Grafana | 如何将数据进行可视化 | [查看本节](#grafana)
+添加一个插件 | 如何制作自己的插件的详细信息 | [链接](plugins/README-zh-CN.md) 
+添加新的指标 | 如何给插件添加指标 | [链接](plugins/HOW-TO-ADD-METRICS-zh-CN.md) 
+贡献 | 如何进行贡献 | [链接](CONTRIBUTING-zh-CN.md)
+
+
+## 我们目前支持的数据源<a id="data-source-plugins"></a>
+
+下面是一个 _数据源插件（data source plugins）_ 的列表，用于收集和处理特定来源的数据。每个插件都有一个 `README.md` 文件，包含基本设置、故障排除和指标信息。
+
+关于建立一个新的 _data source plugins_ 的更多信息，请参见[添加一个插件](plugins/README-zh-CN.md)。
+
+目录 | 内容 | 文档
+------------ | ------------- | -------------
+Jira | 指标，生成 API Token，查找项目/看板ID，配置事务状态和字段名称 | [Link](plugins/jira/README-zh-CN.md) 
+Gitlab | 指标，生成 API Token | [Link](plugins/gitlab/README-zh-CN.md) 
+Jenkins | 指标，生成 API Token | [Link](plugins/jenkins/README-zh-CN.md) 
+
+
+## 用户设置<a id="user-setup"></a>
+
+**注意：如果你只打算运行 Dev Lake，你只需要阅读这一小节**<br>
+**注意：写成 `这样` 的命令需要在你的终端中运行**
+
+### 需要安装的软件包<a id="user-setup-requirements"></a>
+
+- [Docker](https://docs.docker.com/get-docker)
+- [docker-compose](https://docs.docker.com/compose/install/)
+
+**NOTE:** 安装完 Docker 后，你可能需要运行 Docker 应用程序并重新启动你的终端
+
+### 在你的终端中运行的命令<a id="user-setup-commands"></a>
+
+1. 克隆仓库
+
+   ```sh
+   git clone https://github.com/merico-dev/lake.git devlake
+   cd devlake
+   cp .env.example .env
+   ```
+2. 启动 Docker，然后运行 `docker-compose up config-ui` 来启动配置界面。
+
+> 关于如何配置插件的更多信息，请参考 <a href="https://github.com/merico-dev/lake#data-source-plugins" target="_blank">数据源插件</a> 部分
+
+3. 访问 `localhost:4000` 来设置配置文件
+
+4. 运行 `docker-compose up -d` 来启动其他服务
+
+5. 访问 `localhost:4000/triggers` 以运行插件的收集触发器
+
+> 请替换请求正文中的 [gitlab projectId](plugins/gitlab/README-zh-CN.md#如何获取-gitlab-project-id) 和 [jira boardId](plugins/jira/README-zh-CN.md#如何获取-jira-board-id)。对于大型项目，这可能需要20分钟。 (Gitlab 10k+ commits 或 Jira 5k+ 事务)
+
+6. 完成后，点击 *Go to grafana* (用户名: `admin`, 密码: `admin`)
+
+### 设置 Cron job
+通常情况下，我们有定期同步数据的要求。我们提供了一个叫做 `lake-cli` 的工具来满足这个要求。请在 [这里](./cmd/lake-cli/README.md) 查看 `lake-cli` 的用法。 
+
+除此之外，如果你只想使用 Cron job，请在 [这里](./devops/sync/README.md) 查看 `docker-compose` 版本。
+
+
+## 开发者设置<a id="dev-setup"></a>
+
+### 前期准备
+
+- <a href="https://docs.docker.com/get-docker" target="_blank">Docker</a>
+- <a href="https://golang.org/doc/install" target="_blank">Golang</a>
+- Make
+  - Mac (Already installed)
+  - Windows: [Download](http://gnuwin32.sourceforge.net/packages/make.htm)
+  - Ubuntu: `sudo apt-get install build-essential`
+
+### 如何设置开发环境
+1. 进入你想安装本项目的路径，并克隆资源库
+
+   ```sh
+   git clone https://github.com/merico-dev/lake.git
+   cd lake
+   ```
+
+2. 安装 go packages
+
+    ```sh
+    make install
+    ```
+
+3. 将样本配置文件复制到新的本地文件
+
+    ```sh
+    cp .env.example .env
+    ```
+
+4. 启动 Docker
+
+    > 确保在此步骤之前 Docker 正在运行。
+
+    ```sh
+    make compose
+    ```
+
+5. 运行项目
+
+    ```sh
+    make dev
+    ```
+
+6. 发送请求到 /task，创建一个 Jira 任务。这将从 Jira 收集数据
+
+    ```
+    curl -XPOST 'localhost:8080/task' \
+    -H 'Content-Type: application/json' \
+    -d '[{
+        "plugin": "jira",
+        "options": {
+            "boardId": 8
+        }
+    }]'
+    ```
+
+7. 在Grafana仪表板中实现数据的可视化
+
+    _从这里你可以看到丰富的图表，这些图表来自于收集和处理后的数据_
+
+    - 导航到 http://localhost:3002 (用户名: `admin`, 密码: `admin`)
+    - 你也可以创建/修改现有的/保存到 `Dev lake` 中的仪表板
+    - 关于在Dev Lake中使用Grafana的更多信息，请看 [Grafana 文档](docs/GRAFANA.md)
+
+
+## 测试<a id="tests"></a>
+
+运行测试: `make test`
+
+## Grafana<a id="grafana"></a>
+
+我们使用 <a href="https://grafana.com/" target="_blank">Grafana</a> 作为可视化工具，为存储在我们数据库中的数据建立图表。可以使用SQL查询，添加面板来构建、保存和编辑自定义仪表盘。
+
+关于配置和定制仪表盘的所有细节可以在 [Grafana 文档](docs/GRAFANA.md) 中找到。
+
+## 贡献
+
+[CONTRIBUTING.md](CONTRIBUTING.md)
+
+## 需要帮助?
+
+在 <a href="https://discord.com/invite/83rDG6ydVZ" target="_blank">Discord</a> 上给我们发消息
+
+
+
+

README.md

@@ -7,6 +7,11 @@
 ![badge](https://github.com/merico-dev/lake/actions/workflows/test.yml/badge.svg)
 [![Go Report Card](https://goreportcard.com/badge/github.com/merico-dev/lake)](https://goreportcard.com/report/github.com/merico-dev/lake)
 
+| [English](README.md) | [中文](README-zh-CN.md) |
+| --- | --- |
+
+<br>
+
 ### What is Dev Lake?
 
 Dev Lake is the one-stop solution that _**integrates, analyzes, and visualizes**_ software development data throughout the _**software development life cycle (SDLC)**_ for engineering teams.

plugins/HOW-TO-ADD-METRICS-zh-CN.md

@@ -0,0 +1,22 @@
+# 听说你想添加一个新的指标...
+...这显然是个好主意!
+
+你可以从 Jira/GitLab/Jenkins 获取数据，但也许无法得到你想要的指标。别担心! 你可以通过贡献一点代码来获得你想要的任何指标。
+
+1. 决定你的指标是否需要收集新的数据，或者你只是需要处理（Enrich）已有的数据。
+
+2. 如果你需要收集新的数据，那么你将需要：<br>
+  a. 为你想获取的数据创建一个模型<br>
+  b. 将你的新模型添加到插件的初始文件中。这将使 GORM 能够自动迁移定义以创建一个新的 DB 表<br>
+  c. 在 "tasks" 文件夹中创建一个收集器（Collector）。你将需要进行API调用来收集和保存你的新数据。你可能需要做一些研究，以弄清从API返回的字段，以具体捕捉所有你想计算的指标<br>
+  d. 在你获取的数据之上，添加任何额外的 "enrichment" 计算<br>
+  e. 将你的 "collection" 方法添加到插件主包的执行函数中<br>
+  f. 启动项目，发送一个 API 请求来触发你的插件，然后等待数据进来<br>
+  g. 恭喜你，你已经完成了!<br>
+
+3. 如果你不需要新的数据，那么你需要做的就是：在我们已经获取的数据之上添加任何额外的 "enrichment" 计算。
+
+谢谢你的贡献!
+
+-- Dev Lake 团队
+

plugins/README-zh-CN.md

@@ -0,0 +1,102 @@
+# 听说你想建立一个新的插件...
+
+...好消息是，这很容易!
+
+
+## 基本写法
+
+```golang
+type YourPlugin string
+
+func (plugin YourPlugin) Description() string {
+	return "To collect and enrich data from YourPlugin"
+}
+
+func (plugin YourPlugin) Execute(options map[string]interface{}, progress chan<- float32) {
+	logger.Print("Starting YourPlugin execution...")
+
+  // 检查选项中需要的字段
+	projectId, ok := options["projectId"]
+	if !ok {
+		logger.Print("projectId is required for YourPlugin execution")
+		return
+	}
+
+  // 开始收集
+  if err := tasks.CollectProject(projectId); err != nil {
+		logger.Error("Could not collect projects: ", err)
+		return
+	}
+  // 处理错误
+  if err != nil {
+    logger.Error(err)
+  }
+
+  // 导出一个名为 PluginEntry 的变量供 Framework 搜索和加载
+  var PluginEntry YourPlugin //nolint
+}
+```
+
+## 概要
+
+要建立一个新的插件，你将需要做下列事项。你应该选择一个你想看的数据的 API。首先考虑你想看到的指标，然后寻找能够支持这些指标的数据。
+
+## 收集（Collection）
+
+然后你要写一个 `Collection` 来收集数据。你需要阅读一些 API 文档，弄清楚你想在最后的 Grafana 仪表盘中看到哪些指标（配置Grafana是最后一步）。
+
+## 构建一个 `Fetcher` 来执行请求
+
+Plugins/core文件夹包含一个 API 客户端，你可以在自己的插件中实现。它有一些方法，比如Get()。<br>
+每个API处理分页的方式不同，所以你可能需要实现一个 "带分页的获取 "方法。有一种方法是使用 "ant" 包作为管理并发任务的方法：https://github.com/panjf2000/ants
+
+你的 collection 方法可能看起来像这样:
+
+```golang
+func Collect() error {
+	pluginApiClient := CreateApiClient()
+
+	return pluginApiClient.FetchWithPagination("<your_api_url>",
+		func(res *http.Response) error {
+			pluginApiResponse := &ApiResponse{}
+      // 你必须解除对api的响应，才能使用这些结果
+			err := core.UnmarshalResponse(res, pluginApiResponse)
+			if err != nil {
+				logger.Error("Error: ", err)
+				return nil
+			}
+      // 将获取到的数据保存到数据库中
+			for _, value := range *pluginApiResponse {
+				pluginModel := &models.pluginModel{
+					pluginId:       value.pluginId,
+					Title:          value.Title,
+					Message:        value.Message,
+				}
+
+				err = lakeModels.Db.Clauses(clause.OnConflict{
+					UpdateAll: true,
+				}).Create(&pluginModel).Error
+
+				if err != nil {
+					logger.Error("Could not upsert: ", err)
+				}
+			}
+
+			return nil
+		})
+}
+```
+
+请注意 "upsert" 的使用。这对于只保存修改过的记录是很有用的。
+
+## 数据处理（Enrichment）
+  
+一旦你通过 API 收集了数据，你可能想通过以下方式来对这些数据做 ETL。比如：
+
+  - 添加你目前没有的字段
+  - 计算你可能需要的指标字段
+  - 消除你不需要的字段
+
+## 你已经完成了!
+
+祝贺你! 你已经创建了你的第一个插件! 🎖