This is an automated email from the ASF dual-hosted git repository. likyh pushed a commit to branch tapd-zentao-doc in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit f449fc4c7f6eae5c27ff67206a4009617a45134c Author: linyh <[email protected]> AuthorDate: Mon Apr 10 23:22:53 2023 +0800 update doc for tapd and zentao --- docs/Configuration/Tapd.md | 47 +++++++++++++++++--- docs/Configuration/Zentao.md | 26 ++++++++--- docs/DataModels/DevLakeDomainLayerSchema.md | 36 +++++++-------- docs/Overview/SupportedDataSources.md | 69 ++++++++++++++++++++++------- docs/Plugins/tapd.md | 2 +- docs/Plugins/zentao.md | 2 +- 6 files changed, 135 insertions(+), 47 deletions(-) diff --git a/docs/Configuration/Tapd.md b/docs/Configuration/Tapd.md index cf62019b0f..d5d29ef069 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 instructionFor Teambition --- 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..ab90a8bc2a 100644 --- a/docs/Configuration/Zentao.md +++ b/docs/Configuration/Zentao.md @@ -1,5 +1,5 @@ --- -title: "Zentao(Beta)" +title: "Zentao" sidebar_position: 6 description: Config UI instruction for Zentao --- @@ -19,7 +19,8 @@ Name your connection. This should be a valid REST API endpoint - `http://<host>:<port>/api.php/v1/` - The endpoint url should end with `/`. +- or `http://<host>:<port>/zentao/api.php/v1/` + It depends on the path where you deploy zentao. The endpoint url should end with `/`. #### Username/Password @@ -33,12 +34,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 feccd53225..33144bbfb6 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` | Full Refresh | -| GitLab | Source Code Management, Code Review, Issue Tracking, CI/CD (GitLab CI) | Cloud, Community Edition 13.x+ | Available | `gitlab`, `gitextractor` | Full Refresh, Incremental Sync(for `issues`,`MRs`) | -| Jira | Issue Tracking | Cloud, Server 7.x+, Data Center 7.x+ | Available | `jira` | Full Refresh, Incremental Sync(for `issues` and related) | -| Jenkins | CI/CD | 2.263.x+ | Available | `jenkins` | Full Refresh | -| 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 | Cloud | 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(Server) | Available | `sonarqube` | Full Refresh | -| Bamboo | CI/CD | 6.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` | Full Refresh | +| GitLab | Source Code Management, Code Review, Issue Tracking, CI/CD (GitLab CI) | Cloud, Community Edition 13.x+ | Available | `gitlab`, `gitextractor` | Full Refresh, Incremental Sync(for `issues`,`MRs`) | +| Jira | Issue Tracking | Cloud, Server 7.x+, Data Center 7.x+ | Available | `jira` | Full Refresh, Incremental Sync(for `issues` and related) | +| Jenkins | CI/CD | 2.263.x+ | Available | `jenkins` | Full Refresh | +| BitBucket (Beta) | Source Code Management, Code Review | Cloud | Advanced Mode Available | `bitbucket`, `gitextractor` | Full Refresh | +| TAPD | Issue Tracking | Cloud | Advanced Mode Available | `tapd` | Full Refresh, Incremental Sync(for `stories`, `bugs`, `tasks`) | +| Zentao | Issue Tracking | Cloud | 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(Server) | Available | `sonarqube` | Full Refresh | +| Bamboo | CI/CD | 6.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 | ❌ | ❌ | + +### Lento + +| 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 | ✅ | ✅ | diff --git a/docs/Plugins/tapd.md b/docs/Plugins/tapd.md index d4fa912548..0cafe02047 100644 --- a/docs/Plugins/tapd.md +++ b/docs/Plugins/tapd.md @@ -1,5 +1,5 @@ --- -title: "Tapd(Beta)" +title: "Tapd" description: > Tapd Plugin --- diff --git a/docs/Plugins/zentao.md b/docs/Plugins/zentao.md index 43d6398d49..d400c75d10 100644 --- a/docs/Plugins/zentao.md +++ b/docs/Plugins/zentao.md @@ -1,5 +1,5 @@ --- -title: "Zentao(Beta)" +title: "Zentao" description: > Zentao Plugin ---
