[GitHub] [incubator-devlake-website] Startrekzky commented on a diff in pull request #119: docs: translate article "pluginCreate".

[GitBox <gi...@apache.org>]

Startrekzky commented on code in PR #119:
URL: https://github.com/apache/incubator-devlake-website/pull/119#discussion_r932190698


##########
docs/DeveloperManuals/PluginImplementation.md:
##########
@@ -73,7 +71,7 @@ There's a lot of information in the diagram but we don't expect you to digest it
 
 In this guide, we'll walk through how to create a data source plugin from scratch. 
 
-The example in this tutorial comes from DevLake's own needs of managing [CLAs](https://en.wikipedia.org/wiki/Contributor_License_Agreement). Whenever DevLake receives a new PR on GitHub, we need to check if the author has signed a CLA by referencing `https://people.apache.org/public/icla-info.json`. This guide will demonstrate how to collect the ICLA info from Apache API, cache the raw response, and extract the raw data into a relational table ready to be queried.
+Apache requires the project to confirm whether the Contributors and Committers of the project have signed the CLA. So we need to check whether committers have signed the CLA by requesting Apache API and whether contributors have signed by requesting the mailing list. Here we will explain how to request and cache committer information from the Apache API and extract the structured data. There is just an introduction for contributors' at the end of this article.

Review Comment:
   In this section, we will describe how to create a data collection plugin from scratch. The data to be collected is information about all Committers and Contributors of the Apache project, in order to check whether they have signed the CLA.
   - requesting `https://people.apache.org/public/icla-info.json` to get the Committers' information
   - requesting the `mailing list` to get the Contributors' information
   We will focus on demonstrating how to request and cache information about all Committers through the Apache API and extract structured data from it. The collection of Contributors will only be briefly described.



##########
i18n/zh/docusaurus-plugin-content-docs/current/DeveloperManuals/PluginImplementation.md:
##########
@@ -0,0 +1,289 @@
+---
+title: "如何制作一个DevLake插件？"
+sidebar_position: 2
+description: >
+  如何制作一个DevLake插件？
+---
+
+
+如果你喜欢的DevOps工具还没有被DevLake支持，不要担心。实现一个DevLake插件并不困难。在这篇文章中，我们将了解DevLake插件的基础知识，并一起从头开始建立一个插件的例子。
+
+## 什么是插件？
+
+DevLake插件是用Go的`plugin`包构建的共享库，在运行时与DevLake核心挂钩。
+
+一个插件可以通过三种方式扩展DevLake的能力。
+
+1. 与新的数据源集成
+2. 转化/丰富现有数据
+3. 将DevLake数据导出到其他数据系统
+
+
+## 插件是如何工作的？
+
+一个插件主要包括可以由DevLake核心执行的子任务的集合。对于数据源插件，一个子任务可能是从数据源中收集一个实体（例如，来自Jira的问题）。除了子任务，还有一些钩子，插件可以实现自定义其初始化、迁移等。最重要的接口列表见下文。
+
+1. [PluginMeta](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_meta.go) 包含一个插件最少应该实现的接口，只有两个函数；
+   - Description() 返回插件的描述
+   - RootPkgPath() 返回插件的包路径。
+2. [PluginInit](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_init.go) 实现自定义的初始化方法；
+3. [PluginTask](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_task.go) 实现自定义准备数据，其在子任务之前执行；
+4. [PluginApi](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_api.go) 实现插件自定义的API；
+5. [Migratable](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_db_migration.go) 返回插件自定义的数据库迁移的脚本。
+
+下图是一个插件执行的流程：
+
+```mermaid
+flowchart TD
+    subgraph S4[Step4 Extractor 运行流程]
+    direction LR
+    D4[DevLake]
+    D4 -- "Step4.1 创建\n ApiExtractor 并执行" --> E["ExtractXXXMeta.\nEntryPoint"];
+    E <-- "Step4.2 读取raw table" --> E2["RawDataSubTaskArgs\n.Table"];
+    E -- "Step4.3 解析 RawData" --> ApiExtractor.Extract
+    ApiExtractor.Extract -- "返回 gorm 模型" --> E
+    end
+    subgraph S3[Step3 Collector 运行流程]
+    direction LR
+    D3[DevLake]
+    D3 -- "Step3.1 创建\n ApiCollector 并执行" --> C["CollectXXXMeta.\nEntryPoint"];
+    C <-- "Step3.2 创建raw table" --> C2["RawDataSubTaskArgs\n.RAW_BBB_TABLE"];
+    C <-- "Step3.3 构造请求query" --> ApiCollectorArgs.\nQuery/UrlTemplate;
+    C <-. "Step3.4 通过 ApiClient \n请求并返回HTTP" --> A1["HTTP APIs"];
+    C <-- "Step3.5 解析\n并返回请求结果" --> ResponseParser;
+    end
+    subgraph S2[Step2 DevLake 的自定义插件]
+    direction LR
+    D2[DevLake]
+    D2 <-- "Step2.1 在\`Init\` \n初始化插件" --> plugin.Init;
+    D2 <-- "Step2.2 (Optional) 调用\n与返回 migration 脚本" --> plugin.MigrationScripts;
+    D2 <-- "Step2.3 (Optional) \n初始化并返回taskCtx" --> plugin.PrepareTaskData;
+    D2 <-- "Step2.4 返回\n 需要执行的子函数" --> plugin.SubTaskContext;
+    end
+    subgraph S1[Step1 DevLake 的运行]
+    direction LR
+    main -- "通过 \`runner.DirectRun\`\n 移交控制权" --> D1[DevLake];
+    end
+    S1-->S2-->S3-->S4
+```
+图中信息非常多，当然并不期望马上就能消化完，仅仅作为阅读后文的参考即可。
+
+## 一起来实现一个最简单的插件
+
+在本节中，将介绍如何从头创建一个数据收集插件。要收集的数据是 Apache 项目的所有 Committer 和 Contributor，Apache 要求项目确认项目的 Contributor 和 Committer 是否签署了CLA，我们需要通过请求`https://people.apache.org/public/icla-info.json`来检查 Committer、通过请求邮件列表检查 Contributor 是否签署了CLA。这里我们将演示如何从Apache API中请求并缓存所有Committer的信息，并提取出结构化的数据，Contributor 的检查仅做一些思路的介绍。

Review Comment:
   在本节中，我们将介绍如何从头创建一个数据收集插件。要收集的数据是 Apache 项目的所有 Committers 和 Contributors 信息，目的是检查其是否签署了 CLA。我们将通过
   - 请求 `https://people.apache.org/public/icla-info.json` 获取 Committers 信息
   - 请求`邮件列表` 获取 Contributors 信息
   我们将演示如何通过 Apache API 请求并缓存所有 Committers 的信息，并提取出结构化的数据。Contributors 的收集仅做一些思路的介绍。



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@devlake.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org