This is an automated email from the ASF dual-hosted git repository.
yumeng 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 4ab99f2945 update doc for tapd and zentao (#486)
4ab99f2945 is described below
commit 4ab99f294503ee0cabec94bcd08cb7394e253f19
Author: Likyh <[email protected]>
AuthorDate: Sun Apr 23 17:01:13 2023 +0800
update doc for tapd and zentao (#486)
* update doc for tapd and zentao
* fix: update some typo
---
docs/Configuration/Tapd.md | 47 +++++++++++++++++---
docs/Configuration/Zentao.md | 30 +++++++++----
docs/DataModels/DevLakeDomainLayerSchema.md | 36 +++++++--------
docs/Overview/SupportedDataSources.md | 69 ++++++++++++++++++++++-------
4 files changed, 134 insertions(+), 48 deletions(-)
diff --git a/docs/Configuration/Tapd.md b/docs/Configuration/Tapd.md
index cf62019b0f..eeb605e121 100644
--- a/docs/Configuration/Tapd.md
+++ b/docs/Configuration/Tapd.md
@@ -1,7 +1,7 @@
---
-title: "TAPD(Beta)"
+title: "TAPD"
sidebar_position: 6
-description: Config UI instruction for Tapd
+description: Config UI instruction for TAPD
---
Visit config-ui: `http://localhost:4000` and go to `Connections` page.
@@ -30,12 +30,47 @@ For TAPD, we suggest you setting the rate limit to 3500
#### Test and Save Connection
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
-### Step 2 - Configure Blueprint
+### Step 2 - Setting Data Scope
-Similar to other beta plugins, TAPD does not support `project`, which means,
you can only collect TAPD data via blueprint's advanced mode.
+
-Please go to the `Blueprints` page and switch to advanced mode. See how to use
advanced mode and JSON [examples](AdvancedMode.md#6-tapd).
+You can find the campany id in your Tapd company dashboard.
-### Troubleshooting
+
+
+#### Workspaces
+
+Choose the Tapd workspaces to collect.
+
+#### Data Entities
+
+Usually, you don't have to modify this part. However, if you don't want to
collect certain Tapd entities, you can unselect some entities to accerlerate
the collection speed.
+
+- Issue Tracking: Tapd issues, issue comments, issue labels, etc.
+- Cross Domain: Tapd accounts, etc.
+
+### Step 3 - Adding Transformation Rules (Optional)
+
+
+
+Without adding transformation rules, you can not view all charts in
"Engineering Throughput and Cycle Time" dashboards.<br/>
+
+Each Tapd workspace can be configured with different transformation rules.
+
+#### Issue Tracking
+
+- Requirement: choose the issue types to be transformed to "REQUIREMENT".
+- Bug: choose the issue types to be transformed to "BUG".
+- Incident: choose the issue types to be transformed to "INCIDENT".
+- TODO: The issues that are planned but have not been worked on yet
+- IN-PROGRESS: The issues that are work-in-progress
+- DONE: The issues that are completed
+
+### Step 4 - Setting Sync Frequency
+
+You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
+
+## Troubleshooting
If you run into any problem, please check the
[Troubleshooting](/Troubleshooting/Configuration.md) or [create an
issue](https://github.com/apache/incubator-devlake/issues)
+
diff --git a/docs/Configuration/Zentao.md b/docs/Configuration/Zentao.md
index 654ffa8f25..5ce72876c9 100644
--- a/docs/Configuration/Zentao.md
+++ b/docs/Configuration/Zentao.md
@@ -1,7 +1,7 @@
---
-title: "Zentao(Beta)"
+title: "Zentao"
sidebar_position: 6
-description: Config UI instruction for Zentao
+description: Config UI instruction for Zentao(禅道)
---
Visit config-ui: `http://localhost:4000` and go to `Connections` page.
@@ -16,10 +16,9 @@ Name your connection.
#### Endpoint URL
-This should be a valid REST API endpoint
+Please ensure that the REST API endpoint URL is valid. It should be in the
format of either `http://<host>:<port>/api.php/v1/` or
`http://<host>:<port>/zentao/api.php/v1/`.
-- `http://<host>:<port>/api.php/v1/`
- The endpoint url should end with `/`.
+If the initial test fails, please try another endpoint URL as the URL depends
on where Zentao is deployed. Additionally, please ensure that the endpoint URL
ends with a forward slash `/`.
#### Username/Password
@@ -33,12 +32,25 @@ If you are behind a corporate firewall or VPN you may need
to utilize a proxy se
Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
-### Step 2 - Configure Blueprint
+### Step 2 - Setting Data Scope
-Similar to other beta plugins, Zentao does not support `project`, which means,
you can only collect Zentao data via blueprint's advanced mode.
+
-Please go to the `Blueprints` page and switch to advanced mode. See how to use
advanced mode and JSON [examples](AdvancedMode.md#8-zentao).
+#### Projects and Products
-### Troubleshooting
+Please select the Zentao products for collecting stories/bugs and the Zentao
projects for collecting executions. Both will also collect information on
accounts/departments.
+
+#### Data Entities
+
+Usually, you don't have to modify this part. However, if you don't want to
collect certain Lento entities, you can unselect some entities to accerlerate
the collection speed.
+
+- Issue Tracking: Lento issues, issue comments, issue labels, etc.
+
+### Step 3 - Setting Sync Frequency
+
+You can choose how often you would like to sync your data in this step by
selecting a sync frequency option or enter a cron code to specify your prefered
schedule.
+
+## Troubleshooting
If you run into any problem, please check the
[Troubleshooting](/Troubleshooting/Configuration.md) or [create an
issue](https://github.com/apache/incubator-devlake/issues)
+
diff --git a/docs/DataModels/DevLakeDomainLayerSchema.md
b/docs/DataModels/DevLakeDomainLayerSchema.md
index 63edfc29e2..4996fd81ad 100644
--- a/docs/DataModels/DevLakeDomainLayerSchema.md
+++ b/docs/DataModels/DevLakeDomainLayerSchema.md
@@ -1,4 +1,4 @@
----
+---
title: "Domain Layer Schema"
description: >
The data tables to query engineering metrics
@@ -153,14 +153,14 @@ This table shows the work logged under issues. Only Jira
issue worklogs are coll
A `board` is an issue list or a collection of issues. It's the abstraction of
a Jira board, a Jira or TAPD project, a [GitHub repo's issue
list](https://github.com/apache/incubator-devlake/issues) or a GitLab repo's
issue list. This table can be used to filter issues by the boards they belong
to.
-| **field** | **type** | **length** | **description**
| **key** |
-| :------------- | :------- | :--------- |
:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| :------ |
+| **field** | **type** | **length** | **description**
| **key** |
+| :------------- | :------- | :--------- |
:----------------------------------------------------------- | :------ |
| `id` | varchar | 255 | A board's `id` is composed of "<
plugin >:< Entity >:< PK0 >[:PK1]..." <ul><li>For a Github repo's issue list,
the board id is like "< github >:< GithubRepos >:< ConnectionId >:<
GithubRepoId >".<br/>E.g. "github:GithubRepo:384111310"</li> <li>For a Jira
Board, the id is like "< jira >:< JiraSourceId >< JiraBoards >:< ConnectionId
>:< JiraBoardsId >".<br/>E.g. "jira:1:JiraBoards:1:12"</li></ul> | PK |
-| `name` | varchar | 255 | The name of the board. Note: the
board name of a Github repo 'apache/incubator-devlake' is
'apache/incubator-devlake', representing the [default issue
list](https://github.com/apache/incubator-devlake/issues).
| |
-| `description` | varchar | 255 | The description of the board.
| |
-| `url` | varchar | 255 | The url of the board. E.g.
https://github.com/apache/incubator-devlake
| |
-| `created_date` | datetime | 3 | Board creation time
| |
-| `type` | varchar | 255 | Identify scrum and non-scrum board
| |
+| `name` | varchar | 255 | The name of the board. Note: the
board name of a Github repo 'apache/incubator-devlake' is
'apache/incubator-devlake', representing the [default issue
list](https://github.com/apache/incubator-devlake/issues). | |
+| `description` | varchar | 255 | The description of the board.
| |
+| `url` | varchar | 255 | The url of the board. E.g.
https://github.com/apache/incubator-devlake | |
+| `created_date` | datetime | 3 | Board creation time
| |
+| `type` | varchar | 255 | Identify scrum and non-scrum board
| |
#### board_issues
@@ -175,16 +175,16 @@ This table shows the relation between boards and issues.
This table can be used
A `sprint` is the abstraction of Jira sprints, TAPD iterations and GitHub
milestones. A sprint contains a list of issues.
-| **field** | **type** | **length** | **description**
[...]
-| :------------------ | :------- | :--------- |
:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| `id` | varchar | 255 | A sprint's `id` is composed of
"< plugin >:< Entity >:< PK0 >[:PK1]..."<ul><li>A sprint in a Github repo is a
milestone, the sprint id is like "< github >:< GithubRepos >:< GithubRepoId >:<
milestoneNumber >".<br/>E.g. The id for this
[sprint](https://github.com/apache/incubator-devlake/milestone/5) is
"github:GithubRepo:384111310:5"</li><li>For a Jira Board, the id is like "<
jira >:< JiraSourceId >< JiraBoards >:< JiraBoardsId >".<br/>E.g [...]
-| `name` | varchar | 255 | The name of sprint.<br/>For
Github projects, the sprint name is the milestone name. For instance, 'v0.10.0
- Introduce Temporal to DevLake' is the name of this
[sprint](https://github.com/apache/incubator-devlake/milestone/5).
[...]
-| `url` | varchar | 255 | The url of sprint.
[...]
-| `status` | varchar | 255 | There're 3 statuses of a
sprint:<ul><li>CLOSED: a completed sprint</li><li>ACTIVE: a sprint started but
not completed</li><li>FUTURE: a sprint that has not started</li></ul>
[...]
-| `started_date` | datetime | 3 | The start time of a sprint
[...]
-| `ended_date` | datetime | 3 | The planned/estimated end time
of a sprint. It's usually set when planning a sprint.
[...]
-| `completed_date` | datetime | 3 | The actual time to complete a
sprint.
[...]
-| `original_board_id` | datetime | 3 | The id of board where the
sprint first created. This field is not null only when this entity is
transformed from Jira sprints.<br/>In Jira, sprint and board entities have 2
types of relation:<ul><li>A sprint is created based on a specific board. In
this case, board(1):(n)sprint. This field `original_board_id` is used to show
the relation.</li><li>A sprint can be mapped to multiple boards, a board can
also show multiple sprints. In this case [...]
+| **field** | **type** | **length** | **description**
| **key** |
+| :------------------ | :------- | :--------- |
:----------------------------------------------------------- | :----------- |
+| `id` | varchar | 255 | A sprint's `id` is composed of
"< plugin >:< Entity >:< PK0 >[:PK1]..."<ul><li>A sprint in a Github repo is a
milestone, the sprint id is like "< github >:< GithubRepos >:< GithubRepoId >:<
milestoneNumber >".<br/>Eg. The id for this
[sprint](https://github.com/apache/incubator-devlake/milestone/5) is
"github:GithubRepo:384111310:5"</li><li>For a Jira Board, the id is like "<
jira >:< JiraSourceId >< JiraBoards >:< JiraBoardsId >".<br/>Eg. [...]
+| `name` | varchar | 255 | The name of sprint.<br/>For
Github projects, the sprint name is the milestone name. For instance, 'v0.10.0
- Introduce Temporal to DevLake' is the name of this
[sprint](https://github.com/apache/incubator-devlake/milestone/5). |
|
+| `url` | varchar | 255 | The url of sprint.
| |
+| `status` | varchar | 255 | There're 3 statuses of a
sprint:<ul><li>CLOSED: a completed sprint</li><li>ACTIVE: a sprint started but
not completed</li><li>FUTURE: a sprint that has not started</li><li>SUSPENDED:
a sprint that has been suspended</li></ul> | |
+| `started_date` | datetime | 3 | The start time of a sprint
| |
+| `ended_date` | datetime | 3 | The planned/estimated end time
of a sprint. It's usually set when planning a sprint. | |
+| `completed_date` | datetime | 3 | The actual time to complete a
sprint. | |
+| `original_board_id` | datetime | 3 | The id of board where the
sprint first created. This field is not null only when this entity is
transformed from Jira sprints.<br/>In Jira, sprint and board entities have 2
types of relation:<ul><li>A sprint is created based on a specific board. In
this case, board(1):(n)sprint. This field `original_board_id` is used to show
the relation.</li><li>A sprint can be mapped to multiple boards, a board can
also show multiple sprints. In this case [...]
#### sprint_issues
diff --git a/docs/Overview/SupportedDataSources.md
b/docs/Overview/SupportedDataSources.md
index a026eccf4b..27ea6d7a29 100644
--- a/docs/Overview/SupportedDataSources.md
+++ b/docs/Overview/SupportedDataSources.md
@@ -9,21 +9,21 @@ sidebar_position: 5
Apache DevLake(incubating) supports the following data sources. The data from
each data source is collected with one or more plugins. Detailed plugin docs
can be found [here](/docs/Plugins).
-| Data Source | Domain(s)
| Supported Versions | Config UI
Availability | Triggered Plugins | Collection Mode
|
-| ---------------- |
--------------------------------------------------------------------------- |
------------------------------------ | ----------------------- |
--------------------------- |
-------------------------------------------------------------- |
-| GitHub | Source Code Management, Code Review, Issue Tracking,
CI/CD (GitHub Actions) | Cloud | Available
| `github`, `gitextractor` | Incremental Sync
|
-| GitLab | Source Code Management, Code Review, Issue Tracking,
CI/CD (GitLab CI) | Cloud, Community Edition 11+ | Available
| `gitlab`, `gitextractor` | Full Refresh, Incremental Sync(for
`issues`,`MRs`) |
-| Jira | Issue Tracking
| Cloud, Server/Data Center 7.x, 8.x | Available
| `jira` | Full Refresh, Incremental Sync(for `issues`
and related) |
-| Jenkins | CI/CD
| 2.263.x+ | Available
| `jenkins` | Incremental Sync
|
-| BitBucket (Beta) | Source Code Management, Code Review
| Cloud | Advanced Mode
Available | `bitbucket`, `gitextractor` | Full Refresh
|
-| TAPD (Beta) | Issue Tracking
| Cloud | Advanced Mode
Available | `tapd` | Full Refresh, Incremental Sync(for
`stories`, `bugs`, `tasks`) |
-| Zentao (Beta) | Issue Tracking
| v17.x, v18.x | Advanced Mode
Available | `zentao` | Full Refresh
|
-| Gitee (WIP) | Source Code Management, Code Review, Issue Tracking
| Cloud | Not Available
| `gitee`, `gitextractor` | Full Refresh, Incremental Sync(for
`issues`,`MRs`) |
-| PagerDuty (WIP) | Issue Tracking
| Cloud | Not Available
| `pagerduty` | Full Refresh
|
-| Feishu (WIP) | Calendar
| Cloud | Not Available
| `feishu` | Full Refresh
|
-| AE | Source Code Management
| On-prem | Not Available
| `ae` | Full Refresh
|
-| Sonarqube | CODE QUALITY
| SonarQube v8.x, v9.x | Available
| `sonarqube` | Full Refresh
|
-| Bamboo CI(WIP) | CI/CD
| v6.8.1 | Not Available
| `bamboo` | Full Refresh
|
+| Data Source | Domain(s)
| Supported Versions | Config UI Availability | Triggered
Plugins | Collection Mode
|
+| ---------------- |
------------------------------------------------------------ |
---------------------------------- | ----------------------- |
--------------------------- |
------------------------------------------------------------ |
+| GitHub | Source Code Management, Code Review, Issue Tracking,
CI/CD (GitHub Actions) | Cloud | Available
| `github`, `gitextractor` | Incremental Sync
|
+| GitLab | Source Code Management, Code Review, Issue Tracking,
CI/CD (GitLab CI) | Cloud, Community Edition 11+ | Available
| `gitlab`, `gitextractor` | Full Refresh, Incremental Sync(for
`issues`,`MRs`) |
+| Jira | Issue Tracking
| Cloud, Server/Data Center 7.x, 8.x | Available | `jira`
| Full Refresh, Incremental Sync(for `issues` and related) |
+| Jenkins | CI/CD
| 2.263.x+ | Available | `jenkins`
| Incremental Sync |
+| BitBucket (Beta) | Source Code Management, Code Review
| Cloud | Advanced Mode Available |
`bitbucket`, `gitextractor` | Full Refresh
|
+| TAPD (Beta) | Issue Tracking
| Cloud | Advanced Mode Available | `tapd`
| Full Refresh, Incremental Sync(for `stories`, `bugs`,
`tasks`) |
+| Zentao (Beta) | Issue Tracking
| v17.x, v18.x | Advanced Mode Available | `zentao`
| Full Refresh |
+| Gitee (WIP) | Source Code Management, Code Review, Issue Tracking
| Cloud | Not Available | `gitee`,
`gitextractor` | Full Refresh, Incremental Sync(for `issues`,`MRs`)
|
+| PagerDuty (WIP) | Issue Tracking
| Cloud | Not Available | `pagerduty`
| Full Refresh |
+| Feishu (WIP) | Calendar
| Cloud | Not Available | `feishu`
| Full Refresh |
+| AE | Source Code Management
| On-prem | Not Available | `ae`
| Full Refresh |
+| Sonarqube | CODE QUALITY
| SonarQube v8.x, v9.x | Available | `sonarqube`
| Full Refresh |
+| Bamboo CI(WIP) | CI/CD
| v6.8.1 | Not Available | `bamboo`
| Full Refresh |
## Data Collection Scope By Each Plugin
@@ -200,3 +200,42 @@ This table shows the entities collected by each plugin.
Domain layer entities in
| CollectPlanBuildMeta | <10^6 | ❌
| ❌ |
| CollectJobBuildMeta | <10^6 | ❌
| ❌ |
| CollectDeployMeta | 1 | ❌
| ❌ |
+
+### Zentao
+
+| Subtask Name | Estimated Max Number of Request | Does It support
Incremental Collection? | Does It Support Time Filter? |
+| --------------------- | ------------------------------- |
--------------------------------------- | ---------------------------- |
+| CollectExecutionMeta | <10^3 | ❌
| ❌ |
+| CollectStoryMeta | <10^4 | ❌
| ❌ |
+| CollectBugMeta | <10^4 | ❌
| ❌ |
+| CollectTaskMeta | <10^4 | ❌
| ❌ |
+| CollectAccountMeta | ≈10^2 | ❌
| ❌ |
+| CollectDepartmentMeta | ≈10^2 | ❌
| ❌ |
+
+### Tapd
+
+
+| Subtask Name | Estimated Max Number of Request | Does It
support Incremental Collection? | Does It Support Time Filter? |
+| ------------------------------ | ------------------------------- |
--------------------------------------- | ---------------------------- |
+| CollectWorkitemTypesMeta | ≈10 | -
| - |
+| CollectStoryCustomFieldsMeta | ≈10 | -
| - |
+| CollectTaskCustomFieldsMeta | ≈10 | -
| - |
+| CollectBugCustomFieldsMeta | ≈10 | -
| - |
+| CollectStoryCategoriesMeta | ≈10 | -
| - |
+| CollectStoryStatusMeta | ≈10 | -
| - |
+| CollectStoryStatusLastStepMeta | ≈10 | -
| - |
+| CollectBugStatusMeta | ≈10 | -
| - |
+| CollectBugStatusLastStepMeta | ≈10 | -
| - |
+| CollectAccountsMeta | ≈10^3 | ❌
| ❌ |
+| CollectIterationMeta | ≈10^4 | ✅
| ✅ |
+| CollectStoryMeta | ≈10^4 | ✅
| ✅ |
+| CollectBugMeta | ≈10^4 | ✅
| ✅ |
+| CollectTaskMeta | ≈10^4 | ✅
| ✅ |
+| CollectBugChangelogMeta | ≈10^6 | ✅
| ✅ |
+| CollectStoryChangelogMeta | ≈10^6 | ✅
| ✅ |
+| CollectTaskChangelogMeta | ≈10^6 | ✅
| ✅ |
+| CollectWorklogMeta | ≈10^6 | ✅
| ✅ |
+| CollectBugCommitMeta | ≈10^6 | ✅
| ✅ |
+| CollectStoryCommitMeta | ≈10^6 | ✅
| ✅ |
+| CollectTaskCommitMeta | ≈10^6 | ✅
| ✅ |
+| CollectStoryBugMeta | ≈10^6 | ✅
| ✅ |
