You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by kl...@apache.org on 2022/08/22 14:22:39 UTC
[incubator-devlake-website] branch main updated: docs: add plugin model docs (#171)
This is an automated email from the ASF dual-hosted git repository.
klesh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 13265591 docs: add plugin model docs (#171)
13265591 is described below
commit 13265591cf3b4f8d508ce96f6e42b60423d375fc
Author: mappjzc <jz...@qq.com>
AuthorDate: Mon Aug 22 22:22:35 2022 +0800
docs: add plugin model docs (#171)
* docs: add plugin model docs
Add plugin model docs.
Nddtfjiang <zh...@merico.dev>
* docs: Add domain layer model info
Add doc about domain layer model info getting.
Nddtfjiang <zh...@merico.dev>
---
docs/DataModels/DevLakeDomainLayerSchema.md | 15 ++++++++
docs/DeveloperManuals/PluginImplementation.md | 43 +++++++++++++++++++++
.../DeveloperManuals/PluginImplementation.md | 45 +++++++++++++++++++++-
3 files changed, 102 insertions(+), 1 deletion(-)
diff --git a/docs/DataModels/DevLakeDomainLayerSchema.md b/docs/DataModels/DevLakeDomainLayerSchema.md
index a426ed26..3e63afe7 100644
--- a/docs/DataModels/DevLakeDomainLayerSchema.md
+++ b/docs/DataModels/DevLakeDomainLayerSchema.md
@@ -46,6 +46,21 @@ Tables that end with WIP are still under development.
<br/>
+## Get all domain layer model info.
+
+All domain layer models can be accessed by the following method
+
+```golang
+import "github.com/apache/incubator-devlake/models/domainlayer/domaininfo"
+
+domaininfo := domaininfo.GetDomainTablesInfo()
+for _, table := range domaininfo {
+ // do something
+}
+```
+
+If you want to learn more about plugin models,please visit [PluginImplementation](https://devlake.apache.org/docs/DeveloperManuals/PluginImplementation)
+
## DWD Entities - (Data Warehouse Detail)
### Domain 1 - Issue Tracking
diff --git a/docs/DeveloperManuals/PluginImplementation.md b/docs/DeveloperManuals/PluginImplementation.md
index a27609bf..7fc58b05 100644
--- a/docs/DeveloperManuals/PluginImplementation.md
+++ b/docs/DeveloperManuals/PluginImplementation.md
@@ -29,6 +29,7 @@ A plugin mainly consists of a collection of subtasks that can be executed by Dev
3. [PluginTask](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_task.go) enables a plugin to prepare data prior to subtask execution
4. [PluginApi](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_api.go) lets a plugin exposes some self-defined APIs
5. [Migratable](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_db_migration.go) is where a plugin manages its database migrations
+6. [PluginModel](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_model.go) allows other plugins to get the model information of all database tables of the current plugin through the GetTablesInfo() method.If you need to access Domain Layer Models,please visit [DomainLayerSchema](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema/)
The diagram below shows the control flow of executing a plugin:
@@ -284,6 +285,48 @@ Of course, we can use `username/password` to get a token after login mockery. Ju
Look for more related details at https://github.com/apache/incubator-devlake
+#### Step 2.5 Implement the GetTablesInfo() method of the PluginModel interface
+
+As shown in the following gitlab plugin example
+Add all models that need to be accessed by external plugins to the return value.
+
+```golang
+var _ core.PluginModel = (*Gitlab)(nil)
+
+func (plugin Gitlab) GetTablesInfo() []core.Tabler {
+ return []core.Tabler{
+ &models.GitlabConnection{},
+ &models.GitlabAccount{},
+ &models.GitlabCommit{},
+ &models.GitlabIssue{},
+ &models.GitlabIssueLabel{},
+ &models.GitlabJob{},
+ &models.GitlabMergeRequest{},
+ &models.GitlabMrComment{},
+ &models.GitlabMrCommit{},
+ &models.GitlabMrLabel{},
+ &models.GitlabMrNote{},
+ &models.GitlabPipeline{},
+ &models.GitlabProject{},
+ &models.GitlabProjectCommit{},
+ &models.GitlabReviewer{},
+ &models.GitlabTag{},
+ }
+}
+```
+
+You can use it as follow
+
+```
+if pm, ok := plugin.(core.PluginModel); ok {
+ tables := pm.GetTablesInfo()
+ for _, table := range tables {
+ // do something
+ }
+}
+
+```
+
#### Final step: Submit the code as open source code
Good ideas and we encourage contributions~ Let's learn about migration scripts and domain layers to write normative and platform-neutral codes. More info at https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema or contact us for ebullient help.
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/DeveloperManuals/PluginImplementation.md b/i18n/zh/docusaurus-plugin-content-docs/current/DeveloperManuals/PluginImplementation.md
index fffcb020..41c44194 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/DeveloperManuals/PluginImplementation.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/DeveloperManuals/PluginImplementation.md
@@ -30,6 +30,7 @@ DevLake插件是用Go的`plugin`包构建的共享库，在运行时与DevLake
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) 返回插件自定义的数据库迁移的脚本。
+6. [PluginModel](https://github.com/apache/incubator-devlake/blob/main/plugins/core/plugin_model.go) 实现允许其他插件通过 GetTablesInfo() 的方法来获取当前插件的全部数据库表的 model 信息。（若需domain layer的 model 信息，可访问[DomainLayerSchema](https://devlake.apache.org/zh/docs/DataModels/DevLakeDomainLayerSchema/)）
下图是一个插件执行的流程：
@@ -287,7 +288,49 @@ receive data: 272956
更多相关细节请看https://github.com/apache/incubator-devlake
-#### 2.5 将插件提交给开源社区
+#### Step 2.5 实现 PluginModel 接口的 GetTablesInfo() 方法
+
+如下gitlab插件示例所示
+将所有需要被外部插件访问到的 model 均添加到返回值中。
+
+```golang
+var _ core.PluginModel = (*Gitlab)(nil)
+
+func (plugin Gitlab) GetTablesInfo() []core.Tabler {
+ return []core.Tabler{
+ &models.GitlabConnection{},
+ &models.GitlabAccount{},
+ &models.GitlabCommit{},
+ &models.GitlabIssue{},
+ &models.GitlabIssueLabel{},
+ &models.GitlabJob{},
+ &models.GitlabMergeRequest{},
+ &models.GitlabMrComment{},
+ &models.GitlabMrCommit{},
+ &models.GitlabMrLabel{},
+ &models.GitlabMrNote{},
+ &models.GitlabPipeline{},
+ &models.GitlabProject{},
+ &models.GitlabProjectCommit{},
+ &models.GitlabReviewer{},
+ &models.GitlabTag{},
+ }
+}
+```
+
+可以使用如下方式来使用该接口
+
+```
+if pm, ok := plugin.(core.PluginModel); ok {
+ tables := pm.GetTablesInfo()
+ for _, table := range tables {
+ // do something
+ }
+}
+
+```
+
+#### 2.6 将插件提交给开源社区
恭喜你! 第一个插件已经创建完毕! 🎖 我们鼓励开源贡献~ 接下来还需要学习 migrationScripts 和 domainLayers 来编写规范的、平台无关的代码。更多信息请访问https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema，或联系我们以获得热情洋溢的帮助。
