This is an automated email from the ASF dual-hosted git repository.
zky 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 4f178862 docs: update user manuals
4f178862 is described below
commit 4f17886268f69dba036876540707dd1c51b24267
Author: Startrekzky <[email protected]>
AuthorDate: Sat Jul 23 01:01:37 2022 +0800
docs: update user manuals
---
docs/Dashboards/_category_.json | 4 -
docs/DataModels/_category_.json | 2 +-
docs/DeveloperManuals/DeveloperSetup.md | 4 +-
docs/DeveloperManuals/_category_.json | 2 +-
docs/EngineeringMetrics.md | 2 +-
docs/Glossary.md | 2 +-
.../AverageRequirementLeadTime.md | 0
.../CommitCountByAuthor.md | 0
docs/{Dashboards => LiveDemo}/DetailedBugInfo.md | 0
docs/{Dashboards => LiveDemo}/GitHubBasic.md | 0
.../GitHubReleaseQualityAndContributionAnalysis.md | 0
docs/{Dashboards => LiveDemo}/Jenkins.md | 0
docs/{Dashboards => LiveDemo}/WeeklyBugRetro.md | 0
docs/LiveDemo/_category_.json | 4 +
docs/Plugins/_category_.json | 2 +-
docs/QuickStart/DockerComposeSetup.md | 2 +-
docs/{UserManuals => QuickStart}/TemporalSetup.md | 2 +-
docs/QuickStart/_category_.json | 2 +-
docs/UserManuals/{ => ConfigUI}/AdvancedMode.md | 4 +-
docs/UserManuals/ConfigUI/GitHub.md | 86 +++++++++++++++++++++
.../{ConfigUI.md => ConfigUI/Tutorial.md} | 4 +-
docs/UserManuals/ConfigUI/_category_.json | 4 +
.../{ => Dashboards}/GrafanaUserGuide.md | 0
docs/UserManuals/Dashboards/_category_.json | 4 +
docusaurus.config.js | 2 +-
.../img/ConfigUI/github-add-data-connections.png | Bin 0 -> 326031 bytes
.../github-add-transformation-rules-list.png | Bin 0 -> 187342 bytes
.../ConfigUI/github-add-transformation-rules.png | Bin 0 -> 375574 bytes
static/img/ConfigUI/github-set-data-scope.png | Bin 0 -> 274886 bytes
29 files changed, 113 insertions(+), 19 deletions(-)
diff --git a/docs/Dashboards/_category_.json b/docs/Dashboards/_category_.json
deleted file mode 100644
index b27df444..00000000
--- a/docs/Dashboards/_category_.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "label": "Dashboards (Live Demo)",
- "position": 9
-}
diff --git a/docs/DataModels/_category_.json b/docs/DataModels/_category_.json
index e678e712..7420a65e 100644
--- a/docs/DataModels/_category_.json
+++ b/docs/DataModels/_category_.json
@@ -1,4 +1,4 @@
{
"label": "Data Models",
- "position": 5
+ "position": 7
}
diff --git a/docs/DeveloperManuals/DeveloperSetup.md
b/docs/DeveloperManuals/DeveloperSetup.md
index 2a462de1..d75c6e26 100644
--- a/docs/DeveloperManuals/DeveloperSetup.md
+++ b/docs/DeveloperManuals/DeveloperSetup.md
@@ -112,14 +112,14 @@ sidebar_position: 1
]
```
- Please refer to [Pipeline Advanced Mode](../UserManuals/AdvancedMode.md)
for in-depth explanation.
+ Please refer to [Pipeline Advanced
Mode](../UserManuals/ConfigUI/AdvancedMode.md) for in-depth explanation.
10. Click *View Dashboards* button in the top left when done, or visit
`localhost:3002` (username: `admin`, password: `admin`).
We use <a href="https://grafana.com/"; target="_blank">Grafana</a> as a
visualization tool to build charts for the <a
href="https://github.com/merico-dev/lake/wiki/DataModel.Domain-layer-schema";>data
stored in our database</a>. Using SQL queries, we can add panels to build,
save, and edit customized dashboards.
- All the details on provisioning and customizing a dashboard can be found in
the [Grafana Doc](../UserManuals/GrafanaUserGuide.md).
+ All the details on provisioning and customizing a dashboard can be found in
the [Grafana Doc](../UserManuals/Dashboards/GrafanaUserGuide.md).
11. (Optional) To run the tests:
diff --git a/docs/DeveloperManuals/_category_.json
b/docs/DeveloperManuals/_category_.json
index fe67a680..4c436332 100644
--- a/docs/DeveloperManuals/_category_.json
+++ b/docs/DeveloperManuals/_category_.json
@@ -1,4 +1,4 @@
{
"label": "Developer Manuals",
- "position": 4
+ "position": 6
}
diff --git a/docs/EngineeringMetrics.md b/docs/EngineeringMetrics.md
index 2d9a42a5..77760efe 100644
--- a/docs/EngineeringMetrics.md
+++ b/docs/EngineeringMetrics.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 06
+sidebar_position: 8
title: "Engineering Metrics"
linkTitle: "Engineering Metrics"
tags: []
diff --git a/docs/Glossary.md b/docs/Glossary.md
index 9ed93e3d..dc1a046d 100644
--- a/docs/Glossary.md
+++ b/docs/Glossary.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 8
+sidebar_position: 10
title: "Glossary"
linkTitle: "Glossary"
tags: []
diff --git a/docs/Dashboards/AverageRequirementLeadTime.md
b/docs/LiveDemo/AverageRequirementLeadTime.md
similarity index 100%
rename from docs/Dashboards/AverageRequirementLeadTime.md
rename to docs/LiveDemo/AverageRequirementLeadTime.md
diff --git a/docs/Dashboards/CommitCountByAuthor.md
b/docs/LiveDemo/CommitCountByAuthor.md
similarity index 100%
rename from docs/Dashboards/CommitCountByAuthor.md
rename to docs/LiveDemo/CommitCountByAuthor.md
diff --git a/docs/Dashboards/DetailedBugInfo.md
b/docs/LiveDemo/DetailedBugInfo.md
similarity index 100%
rename from docs/Dashboards/DetailedBugInfo.md
rename to docs/LiveDemo/DetailedBugInfo.md
diff --git a/docs/Dashboards/GitHubBasic.md b/docs/LiveDemo/GitHubBasic.md
similarity index 100%
rename from docs/Dashboards/GitHubBasic.md
rename to docs/LiveDemo/GitHubBasic.md
diff --git a/docs/Dashboards/GitHubReleaseQualityAndContributionAnalysis.md
b/docs/LiveDemo/GitHubReleaseQualityAndContributionAnalysis.md
similarity index 100%
rename from docs/Dashboards/GitHubReleaseQualityAndContributionAnalysis.md
rename to docs/LiveDemo/GitHubReleaseQualityAndContributionAnalysis.md
diff --git a/docs/Dashboards/Jenkins.md b/docs/LiveDemo/Jenkins.md
similarity index 100%
rename from docs/Dashboards/Jenkins.md
rename to docs/LiveDemo/Jenkins.md
diff --git a/docs/Dashboards/WeeklyBugRetro.md b/docs/LiveDemo/WeeklyBugRetro.md
similarity index 100%
rename from docs/Dashboards/WeeklyBugRetro.md
rename to docs/LiveDemo/WeeklyBugRetro.md
diff --git a/docs/LiveDemo/_category_.json b/docs/LiveDemo/_category_.json
new file mode 100644
index 00000000..65d519fa
--- /dev/null
+++ b/docs/LiveDemo/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Live Demo",
+ "position": 11
+}
diff --git a/docs/Plugins/_category_.json b/docs/Plugins/_category_.json
index 534bad89..72c1aa5f 100644
--- a/docs/Plugins/_category_.json
+++ b/docs/Plugins/_category_.json
@@ -1,4 +1,4 @@
{
"label": "Plugins",
- "position": 7
+ "position": 9
}
diff --git a/docs/QuickStart/DockerComposeSetup.md
b/docs/QuickStart/DockerComposeSetup.md
index a2973be4..76679859 100644
--- a/docs/QuickStart/DockerComposeSetup.md
+++ b/docs/QuickStart/DockerComposeSetup.md
@@ -34,7 +34,7 @@ sidebar_position: 1
3. Click *View Dashboards* button in the top left when done, or visit
`localhost:3002` (username: `admin`, password: `admin`).
- We use [Grafana](https://grafana.com/) as a visualization tool to build
charts for the [data](../DataModels/DataSupport.md) stored in our database.
- Using SQL queries, we can add panels to build, save, and edit customized
dashboards.
- - All the details on provisioning and customizing a dashboard can be found
in the [Grafana Doc](../UserManuals/GrafanaUserGuide.md).
+ - All the details on provisioning and customizing a dashboard can be found
in the [Grafana Doc](../UserManuals/Dashboards/GrafanaUserGuide.md).
## Upgrade to a newer version
diff --git a/docs/UserManuals/TemporalSetup.md
b/docs/QuickStart/TemporalSetup.md
similarity index 95%
rename from docs/UserManuals/TemporalSetup.md
rename to docs/QuickStart/TemporalSetup.md
index 5a717dec..c5b91c61 100644
--- a/docs/UserManuals/TemporalSetup.md
+++ b/docs/QuickStart/TemporalSetup.md
@@ -1,5 +1,5 @@
---
-title: "Temporal Setup"
+title: "Install via Temporal"
sidebar_position: 6
description: >
The steps to install DevLake in Temporal mode.
diff --git a/docs/QuickStart/_category_.json b/docs/QuickStart/_category_.json
index 133c30f6..877a378f 100644
--- a/docs/QuickStart/_category_.json
+++ b/docs/QuickStart/_category_.json
@@ -1,4 +1,4 @@
{
- "label": "Quick Start",
+ "label": "Getting Started",
"position": 2
}
diff --git a/docs/UserManuals/AdvancedMode.md
b/docs/UserManuals/ConfigUI/AdvancedMode.md
similarity index 97%
rename from docs/UserManuals/AdvancedMode.md
rename to docs/UserManuals/ConfigUI/AdvancedMode.md
index fc41603f..d50b6f0b 100644
--- a/docs/UserManuals/AdvancedMode.md
+++ b/docs/UserManuals/ConfigUI/AdvancedMode.md
@@ -1,6 +1,6 @@
---
-title: "Advanced Mode (WIP)"
-sidebar_position: 3
+title: "Using Advanced Mode (WIP)"
+sidebar_position: 6
description: >
Advanced Mode
---
diff --git a/docs/UserManuals/ConfigUI/GitHub.md
b/docs/UserManuals/ConfigUI/GitHub.md
new file mode 100644
index 00000000..76c7a402
--- /dev/null
+++ b/docs/UserManuals/ConfigUI/GitHub.md
@@ -0,0 +1,86 @@
+---
+title: "Configuring GitHub"
+sidebar_position: 2
+description: Config UI instruction for GitHub
+---
+
+### Step 1 - Add Data Connections
+
+
+#### Connection Name
+Name your connection.
+
+#### Endpoint URL
+This should be a valid REST API endpoint, eg. `https://api.github.com/`. The
url should end with `/`.
+
+#### Auth Token(s)
+GitHub personal access tokens are required to add a connection.
+- Learn about [how to create a personal access
token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+- The data collection speed is relatively slow for GitHub since they have a
**rate limit of [5,000
requests](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)
per hour** (15,000 requests/hour if you pay for GitHub enterprise). You can
accelerate the process by configuring _multiple_ personal access tokens. Please
note that multiple tokens should be created by different GitHub accounts.
Tokens belonging to the same GitHub account share the rate limit.
+
+#### GitHub Proxy URL (Optional)
+If you are behind a corporate firewall or VPN you may need to utilize a proxy
server. Enter a valid proxy server address on your network, e.g.
`http://your-proxy-server.com:1080`
+
+#### Test and Save Connection
+Click `Test Connection`, if the connection is successful, click `Save
Connection` to add the connection.
+
+
+### Step 2 - Setting Data Scope
+
+
+#### Projects
+Enter the GitHub repos to collect. If you want to collect more than 1 repo,
please separate repos with comma. For example,
"apache/incubator-devlake,apache/incubator-devlake-website".
+
+#### Data Entities
+Usually, you don't have to modify this part. However, if you don't want to
collect certain GitHub entities, you can unselect some entities to accerlerate
the collection speed.
+- Source Code Management: repos, refs, commits, etc.
+- Issue Tracking: GitHub issues, issue comments, issue labels, etc.
+- Code Review: PRs, PR comments and reviews, PR commits, etc.
+- Cross Domain: GitHub accounts, etc.
+
+### Step 3 - Adding Transformation Rules (Optional)
+
+
+
+Without adding transformation rules, you can still view the "[GitHub Basic
Metrics](/LiveDemo/GitHubBasic.md)" dashboard. However, if you want to view
"[Weekly Bug Retro](/LiveDemo/WeeklyBugRetro.md)", "Weekly Community Retro" or
other pre-built dashboards, the following transformation rules, especially
"Type/Bug", should be added.<br/>
+
+Each GitHub repo has at most ONE set of transformation rules.
+
+#### Issue Tracking
+
+- Severity: Parse the value of `severity` from issue labels.
+ - when your issue labels for severity level are like 'severity/p0',
'severity/p1', 'severity/p2', then input 'severity/(.*)$'
+ - when your issue labels for severity level are like 'p0', 'p1', 'p2', then
input '(p0|p1|p2)$'
+
+- Component: Same as "Severity".
+
+- Priority: Same as "Severity".
+
+- Type/Requirement: The `type` of issues with labels that match given regular
expression will be set to "REQUIREMENT". Unlike "PR.type", submatch does
nothing, because for issue management analysis, users tend to focus on 3 kinds
of types (Requirement/Bug/Incident), however, the concrete naming varies from
repo to repo, time to time, so we decided to standardize them to help analysts
metrics.
+
+- Type/Bug: Same as "Type/Requirement", with `type` setting to "BUG".
+
+- Type/Incident: Same as "Type/Requirement", with `type` setting to "INCIDENT".
+
+#### Code Review
+
+- Type: The `type` of pull requests will be parsed from PR labels by given
regular expression. For example:
+ - when your labels for PR types are like 'type/feature-development',
'type/bug-fixing' and 'type/docs', please input 'type/(.*)$'
+ - when your labels for PR types are like 'feature-development',
'bug-fixing' and 'docs', please input '(feature-development|bug-fixing|docs)$'
+
+- Component: The `component` of pull requests will be parsed from PR labels by
given regular expression.
+
+#### Additional Settings (Optional)
+
+- Tags Limit: It'll compare the last N pairs of tags to get the "commit diff',
"issue diff" between tags. N defaults to 10.
+ - commit diff: new commits for a tag relative to the previous one
+ - issue diff: issues solved by the new commits for a tag relative to the
previous one
+
+- Tags Pattern: Only tags that meet given regular expression will be counted.
+
+- Tags Order: Only "reverse semver" order is supported for now.
+
+Please click `Save` to save the transformation rules for the repo. In the data
scope list, click `Next Step` to continue configuring.
+
+### 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.
diff --git a/docs/UserManuals/ConfigUI.md
b/docs/UserManuals/ConfigUI/Tutorial.md
similarity index 94%
rename from docs/UserManuals/ConfigUI.md
rename to docs/UserManuals/ConfigUI/Tutorial.md
index 302a7734..9bed49d2 100644
--- a/docs/UserManuals/ConfigUI.md
+++ b/docs/UserManuals/ConfigUI/Tutorial.md
@@ -1,11 +1,11 @@
---
-title: "Config UI"
+title: "Tutorial"
sidebar_position: 1
description: Config UI instruction
---
## Overview
-The DevLake Config UI allows you to configure the data you wish to collect
through a graphical user interface.
+The Apache DevLake Config UI allows you to configure the data you wish to
collect through a graphical user interface.
## Creating a Blueprint
diff --git a/docs/UserManuals/ConfigUI/_category_.json
b/docs/UserManuals/ConfigUI/_category_.json
new file mode 100644
index 00000000..62f99d48
--- /dev/null
+++ b/docs/UserManuals/ConfigUI/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Config UI",
+ "position": 4
+}
diff --git a/docs/UserManuals/GrafanaUserGuide.md
b/docs/UserManuals/Dashboards/GrafanaUserGuide.md
similarity index 100%
rename from docs/UserManuals/GrafanaUserGuide.md
rename to docs/UserManuals/Dashboards/GrafanaUserGuide.md
diff --git a/docs/UserManuals/Dashboards/_category_.json
b/docs/UserManuals/Dashboards/_category_.json
new file mode 100644
index 00000000..0db83c6e
--- /dev/null
+++ b/docs/UserManuals/Dashboards/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Dashboards",
+ "position": 5
+}
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 06164e49..2167836d 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -184,7 +184,7 @@ const versions = require('./versions.json');
},
{
label: 'Dashboards (Live Demo)',
- to: 'docs/Dashboards/GitHubBasic',
+ to: 'docs/LiveDemo/GitHubBasic',
},
],
},
diff --git a/static/img/ConfigUI/github-add-data-connections.png
b/static/img/ConfigUI/github-add-data-connections.png
new file mode 100644
index 00000000..88a38596
Binary files /dev/null and
b/static/img/ConfigUI/github-add-data-connections.png differ
diff --git a/static/img/ConfigUI/github-add-transformation-rules-list.png
b/static/img/ConfigUI/github-add-transformation-rules-list.png
new file mode 100644
index 00000000..cae08c6e
Binary files /dev/null and
b/static/img/ConfigUI/github-add-transformation-rules-list.png differ
diff --git a/static/img/ConfigUI/github-add-transformation-rules.png
b/static/img/ConfigUI/github-add-transformation-rules.png
new file mode 100644
index 00000000..1d8afc8d
Binary files /dev/null and
b/static/img/ConfigUI/github-add-transformation-rules.png differ
diff --git a/static/img/ConfigUI/github-set-data-scope.png
b/static/img/ConfigUI/github-set-data-scope.png
new file mode 100644
index 00000000..7f359984
Binary files /dev/null and b/static/img/ConfigUI/github-set-data-scope.png
differ
