Merge pull request #810 from merico-dev/github-gitlab-README

docs: improve README-zh-CN.md for GitHub and Gitlab

Author: klesh

plugins/github/README-zh-CN.md

@@ -18,40 +18,36 @@
 
 ![image](https://user-images.githubusercontent.com/27032263/141855099-f218f220-1707-45fa-aced-6742ab4c4286.png)
 
-## 获取 Access Token
 
-下面的文档说明了如何获取`Github access token`：
-
-https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+## 配置
 
-## Github 限流
+### 数据源连接配置
+配置界面需要填入以下字段
+- **Connection Name** [`只读`]
+    - ⚠️ 默认值为 "**Github**" 请不要改动。
+- **Endpoint URL** (REST URL, 以 `https://`或`http://`开头)
+    - 应当填入可用的REST API Endpoint。例如 `https://api.github.com/`
+    - ⚠️url应当以`/`结尾
+- **Auth Token(s)** (Personal Access Token)
+    - 如何创建**personal access token**，请参考官方文档[GitHub Docs on Personal Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+    - 填入至少一个token，可以填入多个token并以英文逗号`,`间隔，填入多个token可以加快数据采集速度
 
 对于使用`Basic Authentication`或者`OAuth`的请求，限制为5000次/小时/token
-
 - https://docs.github.com/en/rest/overview/resources-in-the-rest-api
-
 通过在配置文件中设置多个token可以达到更高的请求速率
 
 注意: 如果使用付费的企业版`Github`可以达到15000次/小时/token。
+关于**GitHub REST API**的更多信息请参考官方文档[GitHub Docs on REST](https://docs.github.com/en/rest)
 
-## 配置
-
-在`.evn`文件中需要设置如下配置项
+点击**Save Connection**保存配置。
 
-```
 
-GITHUB_AUTH=XXX
+### 数据源配置
+目前只有一个**可选**配置*Proxy URL*，如果你需要代理才能访问GitHub才需要配置此项
+- **GitHub Proxy URL [`可选`]**
+  - 输入可用的代理服务器地址，例如：`http://your-proxy-server.com:1080`
 
-or...
-
-GITHUB_AUTH=XXX,YYY,ZZZ // 每个token属于不同的用户(可选)
-```
-
-如需使用代理需要设置`.env`文件中的`GITHUB_PROXY`配置项。如果此项没有配置或者配置错误，则不会使用代理。目前只支持`http`和`socks5`两种代理协议。
-
-```
-GITHUB_PROXY=http://127.0.0.1:1080
-```
+点击**Save Settings**保存配置。
 
 
 ## 示例

plugins/github/README.md

@@ -19,21 +19,6 @@ Here are some examples of what we can use `GitHub` data to show:
 
 ![image](https://user-images.githubusercontent.com/27032263/141855099-f218f220-1707-45fa-aced-6742ab4c4286.png)
 
-## Getting Personal Access Token
-
-Here is a link to a guide to get your personal access token from `GitHub`:
-
-https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
-
-## Github rate limits
-
-"For API requests using `Basic Authentication` or `OAuth`, you can make up to 5,000 requests per hour."
-
-- https://docs.github.com/en/rest/overview/resources-in-the-rest-api
-
-If you have a need for more api rate limits, you can set many tokens in the config file and we will use all of your tokens.
-
-NOTE: You can get 15000 requests/hour/token if you pay for `GitHub` enterprise.
 
 ## Configuration
 
@@ -44,10 +29,18 @@ The connection aspect of the configuration screen requires the following key fie
   - ⚠️ Defaults to "**Github**" and may not be changed.
 - **Endpoint URL** (REST URL, starts with `https://` or `http://`)
   - This should be a valid REST API Endpoint eg. `https://api.github.com/`
+  - ⚠️ URL should end with`/`
 - **Auth Token(s)** (Personal Access Token)
+  - For help on **Creating a personal access token**, please see official [GitHub Docs on Personal Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
   - Provide at least one token for Authentication with the . This field accepts a comma-separated list of values for multiple tokens. The data collection will take longer for GitHub since they have a **rate limit of 2k requests per hour**. You can accelerate the process by configuring _multiple_ personal access tokens.
+    
+"For API requests using `Basic Authentication` or `OAuth`, you can make up to 5,000 requests per hour."
 
-For help on **Creating a personal access token**, please see official [GitHub Docs on Personal Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+- https://docs.github.com/en/rest/overview/resources-in-the-rest-api
+
+If you have a need for more api rate limits, you can set many tokens in the config file and we will use all of your tokens.
+
+NOTE: You can get 15000 requests/hour/token if you pay for `GitHub` enterprise.
 
 For an overview of the **GitHub REST API**, please see official [GitHub Docs on REST](https://docs.github.com/en/rest)
 

plugins/gitlab/README-zh-CN.md

@@ -1,5 +1,4 @@
 # Gitlab 插件
-此文档包括 3 部分：指标，配置，如何获取数据。
 
 ## 指标
 此插件通过收集 Gitlab 的数据来计算以下指标。
@@ -19,26 +18,43 @@
 
 ## 配置
 
-插件运行前，你需要在 `.env` 文件中进行以下配置：
+### 数据源连接配置
+配置界面需要填入以下字段
+- **Connection Name** [`只读`]
+    - ⚠️ 默认值为 "**Gitlab**" 请不要改动。
+- **Endpoint URL** (REST URL, 以 `https://`或`http://`开头)
+    - 应当填入可用的REST API Endpoint。例如 `https://gitlab.com/api/v4/`
+    - ⚠️url应当以`/`结尾
+- **Personal Access Token** (HTTP Basic Auth)
+    - 登录你的Gitlab并创建**Personal Access Token**，token长度必须是20个字符。请把生成的token安全保存离开页面后将无法看到。
 
-    ```
-    # Gitlab
-    GITLAB_ENDPOINT=https://gitlab.com/api/v4/
-    GITLAB_AUTH=<your access token>
-    ```
-
-### 获取自己的 Gitlab Endpoint <a id="gitlab-api-token"></a>
-我们使用的 `GITLAB_ENDPOINT`  是 `https://gitlab.com/api/v4/`，但不同用户的 Endpoint 会有所区别。关于这个问题的更多信息，请参考 <a href="https://docs.gitlab.com/ee/api/" target="_blank">Gitlab官方API文档</a>
+    1. 右上角选择**avatar**。
+    2. 选择**Edit profile**。
+    3. 在左侧边栏选择**Access Tokens**。
+    4. 输入**name**并且为此token选择**expiry date**。
+    5. 选择你所需的**scopes**。
+    6. 选择**Create personal access token**。
+如何创建**personal access token**，请参考官方文档[GitLab Docs on Personal Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
 
+关于**GitLab REST API**的更多信息请参考官方文档[GitLab Docs on REST](https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#restful-api)
 
+点击**Save Connection**保存配置。
 
+### 数据源配置
+当前只有一个**可选**配置，它可以让你将JIRA Boards和GitLab Projects关联起来。
 
+- **JIRA Board Mappings [ `可选`]**
+  **Map JIRA Boards to GitLab**。请以以下格式输入映射规则
+```
+# 映射JIRA Board ID 8 ==> Gitlab Projects 8967944,8967945
+<JIRA_BOARD>:<GITLAB_PROJECT_ID>,...; 例如 8:8967944,8967945;9:8967946,8967947
+```
+点击**Save Settings**保存配置。
 
 
-## 如何触发此插件进行数据收集
+## 收集数据
 
-你可以向 `/task` 发起一个POST请求来触发数据收集。由于我们通过 Gitlab project id 来决定收集的数据范畴，因此需要在请求里带上 Gitlab project id<br>
-注意：此请求会在收集全部数据时自动触发，你无需单独执行这一请求，也不需要在 `.env` 文件中设置这个。
+你可以向 `/task` 发起一个POST请求来触发数据收集。
 
     ```
     curl --location --request POST 'localhost:8080/task' \

plugins/gitlab/README.md

@@ -23,6 +23,7 @@ The connection aspect of the configuration screen requires the following key fie
   - ⚠️ Defaults to "**Gitlab**" and may not be changed.
 - **Endpoint URL** (REST URL, starts with `https://` or `http://`)
   - This should be a valid REST API Endpoint eg. `https://gitlab.example.com/api/v4/`
+  - ⚠️ URL should end with`/`
 - **Personal Access Token** (HTTP Basic Auth)
   - Login to your Gitlab Account and create a **Personal Access Token** to authenticate with the API using HTTP Basic Authentication.. The token must be 20 characters long. Save the personal access token somewhere safe. After you leave the page, you no longer have access to the token.