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 030b8f4 docs: add some snapshot for plugin config (#26)
030b8f4 is described below
commit 030b8f44e73beeb8eac6b2113ac6eaf16c49c940
Author: likyh <[email protected]>
AuthorDate: Thu May 19 11:29:50 2022 +0800
docs: add some snapshot for plugin config (#26)
Co-authored-by: linyh <[email protected]>
---
docs/03-Plugins/feishu.md | 10 +-
docs/03-Plugins/github-connection-in-config-ui.png | Bin 0 -> 51159 bytes
docs/03-Plugins/github.md | 13 +-
docs/03-Plugins/gitlab-connection-in-config-ui.png | Bin 0 -> 66616 bytes
docs/03-Plugins/gitlab.md | 24 +--
docs/03-Plugins/jenkins.md | 8 +-
docs/03-Plugins/jira-connection-config-ui.png | Bin 0 -> 76052 bytes
docs/03-Plugins/jira-more-setting-in-config-ui.png | Bin 0 -> 300823 bytes
docs/03-Plugins/jira.md | 217 +++++++++++----------
docs/03-Plugins/tapd.md | 12 ++
10 files changed, 153 insertions(+), 131 deletions(-)
diff --git a/docs/03-Plugins/feishu.md b/docs/03-Plugins/feishu.md
index d05e930..7b60d81 100644
--- a/docs/03-Plugins/feishu.md
+++ b/docs/03-Plugins/feishu.md
@@ -8,7 +8,7 @@ description: >
## Summary
-This plugin collects Feishu data through [Feishu
Openapi](https://open.feishu.cn/document/home/user-identity-introduction/introduction).
+This plugin collects Feishu meeting data through [Feishu
Openapi](https://open.feishu.cn/document/home/user-identity-introduction/introduction).
## Configuration
@@ -49,7 +49,7 @@ You can also trigger data collection by making a POST request
to `/pipelines`.
curl --location --request POST 'localhost:8080/pipelines' \
--header 'Content-Type: application/json' \
--data-raw '
- {
+{
"name": "feishu 20211126",
"tasks": [[{
"plugin": "feishu",
@@ -58,8 +58,6 @@ curl --location --request POST 'localhost:8080/pipelines' \
"rateLimitPerSecond" : 5
}
}]]
- }
+}
'
-```
-
-<br/><br/><br/>
+```
\ No newline at end of file
diff --git a/docs/03-Plugins/github-connection-in-config-ui.png
b/docs/03-Plugins/github-connection-in-config-ui.png
new file mode 100644
index 0000000..5359fb1
Binary files /dev/null and b/docs/03-Plugins/github-connection-in-config-ui.png
differ
diff --git a/docs/03-Plugins/github.md b/docs/03-Plugins/github.md
index f9b55d0..e7b97f7 100644
--- a/docs/03-Plugins/github.md
+++ b/docs/03-Plugins/github.md
@@ -32,6 +32,8 @@ Here are some examples of what we can use `GitHub` data to
show:
### Provider (Datasource) Connection
The connection aspect of the configuration screen requires the following key
fields to connect to the **GitHub API**. As GitHub is a _single-source data
provider_ at the moment, the connection name is read-only as there is only one
instance to manage. As we continue our development roadmap we may enable
_multi-source_ connections for GitHub in the future.
+
+
- **Connection Name** [`READONLY`]
- ⚠️ Defaults to "**Github**" and may not be changed.
- **Endpoint URL** (REST URL, starts with `https://` or `http://`)
@@ -39,13 +41,14 @@ The connection aspect of the configuration screen requires
the following key fie
- ⚠️ 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.
+ - Provide at least one token for Authentication.
+ - 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 5k 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 API requests using `Basic Authentication` or `OAuth`, you can make up to
[5,000
requests](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
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.
+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.
@@ -87,7 +90,7 @@ You can also trigger data collection by making a POST request
to `/pipelines`.
curl --location --request POST 'localhost:8080/pipelines' \
--header 'Content-Type: application/json' \
--data-raw '
- {
+{
"name": "github 20211126",
"tasks": [[{
"plugin": "github",
@@ -96,7 +99,7 @@ curl --location --request POST 'localhost:8080/pipelines' \
"owner": "merico-dev"
}
}]]
- }
+}
'
```
<br/><br/><br/>
diff --git a/docs/03-Plugins/gitlab-connection-in-config-ui.png
b/docs/03-Plugins/gitlab-connection-in-config-ui.png
new file mode 100644
index 0000000..7aacee8
Binary files /dev/null and b/docs/03-Plugins/gitlab-connection-in-config-ui.png
differ
diff --git a/docs/03-Plugins/gitlab.md b/docs/03-Plugins/gitlab.md
index cec16d9..855bd02 100644
--- a/docs/03-Plugins/gitlab.md
+++ b/docs/03-Plugins/gitlab.md
@@ -7,23 +7,25 @@ description: >
## Metrics
-Metric Name | Description
-:------------ | :-------------
-Pull Request Count | Number of Pull/Merge Requests
-Pull Request Pass Rate | Ratio of Pull/Merge Review requests to merged
-Pull Request Reviewer Count | Number of Pull/Merge Reviewers
-Pull Request Review Time | Time from Pull/Merge created time until merged
-Commit Author Count | Number of Contributors
-Commit Count | Number of Commits
-Added Lines | Accumulated Number of New Lines
-Deleted Lines | Accumulated Number of Removed Lines
-Pull Request Review Rounds | Number of cycles of commits followed by
comments/final merge
+| Metric Name | Description
|
+|:----------------------------|:-------------------------------------------------------------|
+| Pull Request Count | Number of Pull/Merge Requests
|
+| Pull Request Pass Rate | Ratio of Pull/Merge Review requests to merged
|
+| Pull Request Reviewer Count | Number of Pull/Merge Reviewers
|
+| Pull Request Review Time | Time from Pull/Merge created time until merged
|
+| Commit Author Count | Number of Contributors
|
+| Commit Count | Number of Commits
|
+| Added Lines | Accumulated Number of New Lines
|
+| Deleted Lines | Accumulated Number of Removed Lines
|
+| Pull Request Review Rounds | Number of cycles of commits followed by
comments/final merge |
## Configuration
### Provider (Datasource) Connection
The connection aspect of the configuration screen requires the following key
fields to connect to the **GitLab API**. As GitLab is a _single-source data
provider_ at the moment, the connection name is read-only as there is only one
instance to manage. As we continue our development roadmap we may enable
_multi-source_ connections for GitLab in the future.
+
+
- **Connection Name** [`READONLY`]
- ⚠️ Defaults to "**Gitlab**" and may not be changed.
- **Endpoint URL** (REST URL, starts with `https://` or `http://`)
diff --git a/docs/03-Plugins/jenkins.md b/docs/03-Plugins/jenkins.md
index a00e892..6e67e95 100644
--- a/docs/03-Plugins/jenkins.md
+++ b/docs/03-Plugins/jenkins.md
@@ -6,7 +6,6 @@ description: >
# Jenkins
-
## Summary
This plugin collects Jenkins data through [Remote Access
API](https://www.jenkins.io/doc/book/using/remote-access-api/). It then
computes and visualizes various devops metrics from the Jenkins data.
@@ -15,9 +14,9 @@ This plugin collects Jenkins data through [Remote Access
API](https://www.jenkin
## Metrics
-| Metric Name | Description |
-| ------------ | ------------- |
-| Build Count | The number of builds created |
+| Metric Name | Description |
+|:-------------------|:------------------------------------|
+| Build Count | The number of builds created |
| Build Success Rate | The percentage of successful builds |
## Configuration
@@ -60,5 +59,4 @@ In order to collect data from Jenkins, you have to compose a
JSON looks like fol
## Relationship between job and build
Build is kind of a snapshot of job. Running job each time creates a build.
-
<br/><br/><br/>
diff --git a/docs/03-Plugins/jira-connection-config-ui.png
b/docs/03-Plugins/jira-connection-config-ui.png
new file mode 100644
index 0000000..df2e8e3
Binary files /dev/null and b/docs/03-Plugins/jira-connection-config-ui.png
differ
diff --git a/docs/03-Plugins/jira-more-setting-in-config-ui.png
b/docs/03-Plugins/jira-more-setting-in-config-ui.png
new file mode 100644
index 0000000..dffb0c9
Binary files /dev/null and b/docs/03-Plugins/jira-more-setting-in-config-ui.png
differ
diff --git a/docs/03-Plugins/jira.md b/docs/03-Plugins/jira.md
index ade0a25..6fb47e1 100644
--- a/docs/03-Plugins/jira.md
+++ b/docs/03-Plugins/jira.md
@@ -9,37 +9,45 @@ description: >
This plugin collects Jira data through Jira Cloud REST API. It then computes
and visualizes various engineering metrics from the Jira data.
-<img width="2035" alt="Screen Shot 2021-09-10 at 4 01 55 PM"
src="https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png"/>
+<img width="2035" alt="jira metric display"
src="https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png";>
## Project Metrics This Covers
-| Metric Name | Description |
-| ------------| ------------ |
-| Requirement Count | Number of issues with type "Requirement" |
-| Requirement Lead Time | Lead time of issues with type "Requirement" |
-| Requirement Delivery Rate | Ratio of delivered requirements to all
requirements |
-| Requirement Granularity | Number of story points associated with an issue |
-| Bug Count | Number of issues in type "Bug". Bugs are defects found during
testing |
-| Bug Age | Lead time of issues in type "Bug". both new and deleted lines
count |
-| Bugs Count per 1k Lines of Code | Amount of bugs per 1000 lines of code |
-| Incident Count | Number of issues with type "Incident". Incidents are
defects found when running in production |
-| Incident Age | Lead time of issues with type "Incident" |
-| Incident Count per 1k Lines of Code | Amount of incidents per 1000 lines of
code |
+| Metric Name | Description
|
+|:------------------------------------|:-----------------------------------------------------------------------------------------------|
+| Requirement Count | Number of issues with type
"Requirement" |
+| Requirement Lead Time | Lead time of issues with type
"Requirement" |
+| Requirement Delivery Rate | Ratio of delivered requirements
to all requirements |
+| Requirement Granularity | Number of story points associated with
an issue |
+| Bug Count | Number of issues with type
"Bug"<br><i>bugs are found during testing</i> |
+| Bug Age | Lead time of issues with type
"Bug"<br><i>both new and deleted lines count</i> |
+| Bugs Count per 1k Lines of Code | Amount of bugs per 1000 lines
of code |
+| Incident Count | Number of issues with type
"Incident"<br><i>incidents are found when running in production</i> |
+| Incident Age | Lead time of issues with type
"Incident" |
+| Incident Count per 1k Lines of Code | Amount of incidents per 1000 lines of
code |
## Configuration
In order to fully use this plugin, you will need to set various configurations
via Dev Lake's `config-ui` service. Open `config-ui` on browser, by default the
URL is http://localhost:4000, then go to **Data Integrations / JIRA** page.
JIRA plugin currently supports multiple data connections, Here you can **add**
new connection to your JIRA connection or **update** the settings if needed.
-For each connection, you will need to set up following items:
+For each connection, you will need to set up following items first:
+
+
- Connection Name: This allow you to distinguish different connections.
-- Endpoint URL: The JIRA instance api endpoint, for JIRA Cloud Service, it
would be: `https://{mydomain}.atlassian.net/rest`. devlake officially supports
JIRA Cloud Service on atlassian.net, may or may not work for JIRA Server
Instance.
+- Endpoint URL: The JIRA instance api endpoint, for JIRA Cloud Service, it
would be: `https://<mydomain>.atlassian.net/rest`. devlake officially supports
JIRA Cloud Service on atlassian.net, may or may not work for JIRA Server
Instance.
- Basic Auth Token: First, generate a **JIRA API TOKEN** for your JIRA account
on JIRA console (see [Generating API token](#generating-api-token)), then, in
`config-ui` click the KEY icon on the right side of the input to generate a
full `HTTP BASIC AUTH` token for you.
+- Proxy Url: Just use when you want collect through VPN.
+
+### More custom configuration
+If you want to add more custom config, you can click "settings" to change
these config
+
- Issue Type Mapping: JIRA is highly customizable, each JIRA instance may have
a different set of issue types than others. In order to compute and visualize
metrics for different instances, you need to map your issue types to standard
ones. See [Issue Type Mapping](#issue-type-mapping) for detail.
- Epic Key: unfortunately, epic relationship implementation in JIRA is based
on `custom field`, which is vary from instance to instance. Please see [Find
Out Custom Fields](#find-out-custom-fields).
- Story Point Field: same as Epic Key.
- Remotelink Commit SHA:A regular expression that matches commit links to
determine whether an external link is a link to a commit. Taking gitlab as an
example, to match all commits similar to
https://gitlab.com/merico-dev/ce/example-repository/-/commit/8ab8fb319930dbd8615830276444b8545fd0ad24,
you can directly use the regular expression **/commit/([0-9a-f]{40})$**
+
### Generating API token
1. Once logged into Jira, visit the url
`https://id.atlassian.com/manage-profile/security/api-tokens`
2. Click the **Create API Token** button, and give it any label name
@@ -50,9 +58,9 @@ For each connection, you will need to set up following items:
Devlake supports 3 standard types, all metrics are computed based on these
types:
- - `Bug`: Problems found during `test` phase, before they can reach the
production environment.
- - `Incident`: Problems went through `test` phash, got deployed into
production environment.
- - `Requirement`: Normally, it would be `Story` on your instance if you
adopted SCRUM.
+ - `Bug`: Problems found during `test` phase, before they can reach the
production environment.
+ - `Incident`: Problems went through `test` phash, got deployed into
production environment.
+ - `Requirement`: Normally, it would be `Story` on your instance if you
adopted SCRUM.
You can may map arbitrary **YOUR OWN ISSUE TYPE** to a single **STANDARD ISSUE
TYPE**, normally, one would map `Story` to `Requirement`, but you could map
both `Story` and `Task` to `Requirement` if that was your case. Those
unspecified type would be copied as standard type directly for your
convenience, so you don't need to map your `Bug` to standard `Bug`.
@@ -68,18 +76,19 @@ Please follow this guide: [How to find Jira the custom
field ID in Jira?](https:
In order to collect data from JIRA, you have to compose a JSON looks like
following one, and send it via `Triggers` page on `config-ui`.
<font color="#ED6A45">Warning: Data collection only supports single-task
execution, and the results of concurrent multi-task execution may not meet
expectations.</font>
-```[
- [
- {
- "plugin": "jira",
- "options": {
- "connectionId": 1,
- "boardId": 8,
- "since": "2006-01-02T15:04:05Z"
- }
+```
+[
+ [
+ {
+ "plugin": "jira",
+ "options": {
+ "connectionId": 1,
+ "boardId": 8,
+ "since": "2006-01-02T15:04:05Z"
}
- ]
+ }
]
+]
```
- `connectionId`: The `ID` field from **JIRA Integration** page.
@@ -109,69 +118,69 @@ Your board id is used in all REST requests to Apache
DevLake. You do not need to
1. Get all data connection
```GET /plugins/jira/connections
- [
- {
- "ID": 14,
- "CreatedAt": "2021-10-11T11:49:19.029Z",
- "UpdatedAt": "2021-10-11T11:49:19.029Z",
- "name": "test-jira-connection",
- "endpoint": "https://merico.atlassian.net/rest";,
- "basicAuthEncoded": "basicAuth",
- "epicKeyField": "epicKeyField",
+[
+ {
+ "ID": 14,
+ "CreatedAt": "2021-10-11T11:49:19.029Z",
+ "UpdatedAt": "2021-10-11T11:49:19.029Z",
+ "name": "test-jira-connection",
+ "endpoint": "https://merico.atlassian.net/rest";,
+ "basicAuthEncoded": "basicAuth",
+ "epicKeyField": "epicKeyField",
"storyPointField": "storyPointField"
- }
- ]
+ }
+]
```
2. Create a new data connection
```POST /plugins/jira/connections
- {
- "name": "jira data connection name",
- "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
+{
+ "name": "jira data connection name",
+ "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
"basicAuthEncoded": "generated by `echo -n {jira login email}:{jira token}
| base64`",
- "epicKeyField": "name of customfield of epic key",
- "storyPointField": "name of customfield of story point",
- "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
- "userType": {
- "standardType": "devlake standard type"
- }
- }
- }
+ "epicKeyField": "name of customfield of epic key",
+ "storyPointField": "name of customfield of story point",
+ "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
+ "userType": {
+ "standardType": "devlake standard type"
+ }
+ }
+}
```
3. Update data connection
```PUT /plugins/jira/connections/:connectionId
- {
- "name": "jira data connection name",
- "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
+{
+ "name": "jira data connection name",
+ "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
"basicAuthEncoded": "generated by `echo -n {jira login email}:{jira token}
| base64`",
- "epicKeyField": "name of customfield of epic key",
- "storyPointField": "name of customfield of story point",
- "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
- "userType": {
- "standardType": "devlake standard type",
- }
- }
- }
+ "epicKeyField": "name of customfield of epic key",
+ "storyPointField": "name of customfield of story point",
+ "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
+ "userType": {
+ "standardType": "devlake standard type",
+ }
+ }
+}
```
4. Get data connection detail
```GET /plugins/jira/connections/:connectionId
- {
- "name": "jira data connection name",
- "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
+{
+ "name": "jira data connection name",
+ "endpoint": "jira api endpoint, i.e. https://merico.atlassian.net/rest";,
"basicAuthEncoded": "generated by `echo -n {jira login email}:{jira token}
| base64`",
- "epicKeyField": "name of customfield of epic key",
- "storyPointField": "name of customfield of story point",
- "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
- "userType": {
- "standardType": "devlake standard type",
- }
- }
- }
+ "epicKeyField": "name of customfield of epic key",
+ "storyPointField": "name of customfield of story point",
+ "typeMappings": { // optional, send empty object to delete all
typeMappings of the data connection
+ "userType": {
+ "standardType": "devlake standard type",
+ }
+ }
+}
```
5. Delete data connection
@@ -184,30 +193,30 @@ Your board id is used in all REST requests to Apache
DevLake. You do not need to
1. Get all type mappings
```GET /plugins/jira/connections/:connectionId/type-mappings
- [
- {
- "jiraConnectionId": 16,
- "userType": "userType",
- "standardType": "standardType"
- }
- ]
+[
+ {
+ "jiraConnectionId": 16,
+ "userType": "userType",
+ "standardType": "standardType"
+ }
+]
```
2. Create a new type mapping
```POST /plugins/jira/connections/:connectionId/type-mappings
- {
- "userType": "userType",
- "standardType": "standardType"
- }
+{
+ "userType": "userType",
+ "standardType": "standardType"
+}
```
3. Update type mapping
```PUT /plugins/jira/connections/:connectionId/type-mapping/:userType
- {
- "standardType": "standardTypeUpdated"
- }
+{
+ "standardType": "standardTypeUpdated"
+}
```
@@ -221,22 +230,22 @@ For example:
Requests to
http://your_devlake_host/plugins/jira/connections/1/proxy/rest/agile/1.0/board/8/sprint
would forward to https://your_jira_host/rest/agile/1.0/board/8/sprint
```GET /plugins/jira/connections/:connectionId/proxy/rest/*path
- {
- "maxResults": 1,
- "startAt": 0,
- "isLast": false,
- "values": [
- {
- "id": 7,
- "self": "https://merico.atlassian.net/rest/agile/1.0/sprint/7";,
- "state": "closed",
- "name": "EE Sprint 7",
- "startDate": "2020-06-12T00:38:51.882Z",
- "endDate": "2020-06-26T00:38:00.000Z",
- "completeDate": "2020-06-22T05:59:58.980Z",
- "originBoardId": 8,
- "goal": ""
- }
- ]
- }
+{
+ "maxResults": 1,
+ "startAt": 0,
+ "isLast": false,
+ "values": [
+ {
+ "id": 7,
+ "self": "https://merico.atlassian.net/rest/agile/1.0/sprint/7";,
+ "state": "closed",
+ "name": "EE Sprint 7",
+ "startDate": "2020-06-12T00:38:51.882Z",
+ "endDate": "2020-06-26T00:38:00.000Z",
+ "completeDate": "2020-06-22T05:59:58.980Z",
+ "originBoardId": 8,
+ "goal": ""
+ }
+ ]
+}
```
diff --git a/docs/03-Plugins/tapd.md b/docs/03-Plugins/tapd.md
new file mode 100644
index 0000000..24b124d
--- /dev/null
+++ b/docs/03-Plugins/tapd.md
@@ -0,0 +1,12 @@
+# Feishu
+
+## Summary
+
+This plugin collects tapd data.
+
+This plugin is in developing so that cannot modify settings in config-ui.
+
+## Configuration
+
+In order to fully use this plugin, you will need to get
endpoint/basic_auth_encoded/rate_limit and insert it into table
`_tool_tapd_connections`.
+
![https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png"/](https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png"/){kind=link}
![https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png"](https://user-images.githubusercontent.com/2908155/132926143-7a31d37f-22e1-487d-92a3-cf62e402e5a8.png"){kind=link}