You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by ly...@apache.org on 2023/12/09 03:23:57 UTC
(incubator-devlake-website) branch main updated (17a8e1f6ee -> 3a7ef252ee)
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
from 17a8e1f6ee docs: remove versions prior to v0.15 (#686)
new 83751aa1a0 docs: add a quick start for DevLake
new e597d26483 docs: re-organize the index of configuration docs
new 370514e935 docs: add the dashboard part to config UI tutorial
new 06eb5901a2 docs: add the project organization doc to v0.18
new 3a7ef252ee docs: update the plugin status in the page title
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/Configuration/APIKeys.md | 2 +-
docs/Configuration/AdvancedMode.md | 2 +-
docs/Configuration/BitBucket.md | 2 +-
docs/Configuration/Dashboards/_category_.json | 2 +-
docs/Configuration/GitHub.md | 2 +-
docs/Configuration/GitLab.md | 2 +-
.../Configuration}/HowToOrganizeDevlakeProjects.md | 8 ++++----
docs/Configuration/Jenkins.md | 2 +-
docs/Configuration/Jira.md | 2 +-
docs/Configuration/PagerDuty.md | 2 +-
docs/Configuration/SonarQube.md | 4 ++--
docs/Configuration/Tapd.md | 2 +-
docs/Configuration/TeamConfiguration.md | 2 +-
docs/Configuration/Teambition.md | 4 ++--
docs/Configuration/Tutorial.md | 4 +++-
docs/Configuration/Zentao.md | 2 +-
docs/Configuration/webhook.md | 4 ++--
docs/GettingStarted/DockerComposeSetup.md | 2 +-
docs/GettingStarted/HelmSetup.md | 2 +-
docs/GettingStarted/QuickStart.md | 17 +++++++++++++++++
docs/GettingStarted/Upgrade.md | 2 --
docs/Plugins/bamboo.md | 4 ++--
docs/Plugins/bitbucket.md | 2 +-
docs/Plugins/tapd.md | 2 +-
docs/Plugins/teambition.md | 2 +-
docs/Plugins/zentao.md | 2 +-
versioned_docs/version-v0.18/Configuration/Tutorial.md | 4 +++-
.../HowToOrganizeDevlakeProjects/create_project_1.png | Bin
.../HowToOrganizeDevlakeProjects/create_project_2.png | Bin
.../navigate_to_dora_1.png | Bin
.../navigate_to_dora_2.png | Bin
.../observe_metrics_by_project_panel.png | Bin
.../HowToOrganizeDevlakeProjects/project_pipeline.png | Bin
.../project_use_case_1.png | Bin
.../project_use_case_2.png | Bin
.../GettingStarted/HowToOrganizeDevlakeProjects.md | 6 +++---
versioned_docs/version-v0.19/Configuration/Tutorial.md | 4 +++-
versioned_docs/version-v0.20/Configuration/Tutorial.md | 5 ++++-
38 files changed, 63 insertions(+), 39 deletions(-)
copy {versioned_docs/version-v0.19/GettingStarted => docs/Configuration}/HowToOrganizeDevlakeProjects.md (97%)
create mode 100644 docs/GettingStarted/QuickStart.md
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/create_project_1.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/create_project_2.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_1.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_2.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/observe_metrics_by_project_panel.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/project_pipeline.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_1.png (100%)
copy {docs => versioned_docs/version-v0.18}/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_2.png (100%)
rename {docs => versioned_docs/version-v0.18}/GettingStarted/HowToOrganizeDevlakeProjects.md (97%)
(incubator-devlake-website) 05/05: docs: update the plugin status in the page title
Posted by ly...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 3a7ef252ee8b371fda7d5a4884e9f22d4d7c2920
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Fri Dec 8 20:59:02 2023 +0800
docs: update the plugin status in the page title
---
docs/Plugins/bamboo.md | 4 ++--
docs/Plugins/bitbucket.md | 2 +-
docs/Plugins/tapd.md | 2 +-
docs/Plugins/teambition.md | 2 +-
docs/Plugins/zentao.md | 2 +-
5 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/Plugins/bamboo.md b/docs/Plugins/bamboo.md
index e67ae358d6..8dc9b49aa9 100644
--- a/docs/Plugins/bamboo.md
+++ b/docs/Plugins/bamboo.md
@@ -1,5 +1,5 @@
---
-title: "Bamboo(WIP)"
+title: "Bamboo"
description: >
Bamboo Plugin
---
@@ -13,7 +13,7 @@ This plugin collects Bamboo's CI data through [API](https://developer.atlassian.
## Supported Versions
-Will be available for Bamboo v6.8.1+. Check [this doc](https://devlake.apache.org/docs/Overview/SupportedDataSources#data-sources-and-data-plugins) for more details.
+Only Bamboo v6.8.1+ is supported as of v0.20. Check [this doc](https://devlake.apache.org/docs/Overview/SupportedDataSources#data-sources-and-data-plugins) for more details.
## Entities
diff --git a/docs/Plugins/bitbucket.md b/docs/Plugins/bitbucket.md
index 6cde9fe365..17a4cd8119 100644
--- a/docs/Plugins/bitbucket.md
+++ b/docs/Plugins/bitbucket.md
@@ -1,5 +1,5 @@
---
-title: "BitBucket(Beta)"
+title: "BitBucket Cloud"
description: >
BitBucket Plugin
---
diff --git a/docs/Plugins/tapd.md b/docs/Plugins/tapd.md
index 829954cdba..fde52d1f92 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/teambition.md b/docs/Plugins/teambition.md
index 601e238476..2bf5f77bf2 100644
--- a/docs/Plugins/teambition.md
+++ b/docs/Plugins/teambition.md
@@ -1,6 +1,6 @@
---
-title: "Teambition(Beta)"
+title: "Teambition(WIP)"
description: >
Teambition Plugin
---
diff --git a/docs/Plugins/zentao.md b/docs/Plugins/zentao.md
index 223556e5c0..1ceb9f508a 100644
--- a/docs/Plugins/zentao.md
+++ b/docs/Plugins/zentao.md
@@ -1,5 +1,5 @@
---
-title: "Zentao(Beta)"
+title: "Zentao"
description: >
Zentao Plugin
---
(incubator-devlake-website) 03/05: docs: add the dashboard part to config UI tutorial
Posted by ly...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 370514e935002cedeec51a01e729ac21d57cbfae
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Fri Dec 8 20:58:03 2023 +0800
docs: add the dashboard part to config UI tutorial
---
docs/Configuration/Tutorial.md | 4 +++-
versioned_docs/version-v0.18/Configuration/Tutorial.md | 4 +++-
versioned_docs/version-v0.19/Configuration/Tutorial.md | 4 +++-
versioned_docs/version-v0.20/Configuration/Tutorial.md | 5 ++++-
4 files changed, 13 insertions(+), 4 deletions(-)
diff --git a/docs/Configuration/Tutorial.md b/docs/Configuration/Tutorial.md
index b00fb5fa65..42ac5a5f33 100644
--- a/docs/Configuration/Tutorial.md
+++ b/docs/Configuration/Tutorial.md
@@ -19,7 +19,7 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 1.3 - Add scope config (optional). Define the specific data entities within the data scope for collection or apply transformation rules to the raw API responses.
### Step 2 - Collect Data in a Project
-- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](/docs/GettingStarted/HowToOrganizeDevlakeProjects.md) for more details.
+- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](/docs/Configuration/HowToOrganizeDevlakeProjects.md) for more details.
- Step 2.2 - Associate connection(s) with the project. When associating a connection with a project, you can select specific data scopes. All connections linked to the same project will be considered part of the same project for calculating DORA metrics.
@@ -27,6 +27,8 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 2.4 - Start data collection. Choose the desired [mode](#step-2---collect-data-in-a-project) for collecting data.
+### Step 3 - Check the Data in Grafana Dashboards
+To view the collected data, click on the "Dashboards" button located in the top-right corner of Config UI. For detailed instructions, please refer to the [Grafana manuals](Dashboards/GrafanaUserGuide.md).
## Examples
For detailed examples, please refer to the respective documentation files available in this folder, such as [GitHub configuration](GitHub.md), [GitLab configuration](GitLab.md), [Jira configuration](Jira.md) and more. They provide step-by-step instructions and guidance for configuring DevLake with different platforms.
diff --git a/versioned_docs/version-v0.18/Configuration/Tutorial.md b/versioned_docs/version-v0.18/Configuration/Tutorial.md
index b00fb5fa65..c130fb0ebc 100644
--- a/versioned_docs/version-v0.18/Configuration/Tutorial.md
+++ b/versioned_docs/version-v0.18/Configuration/Tutorial.md
@@ -19,7 +19,7 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 1.3 - Add scope config (optional). Define the specific data entities within the data scope for collection or apply transformation rules to the raw API responses.
### Step 2 - Collect Data in a Project
-- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](/docs/GettingStarted/HowToOrganizeDevlakeProjects.md) for more details.
+- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](../GettingStarted/HowToOrganizeDevlakeProjects) for more details.
- Step 2.2 - Associate connection(s) with the project. When associating a connection with a project, you can select specific data scopes. All connections linked to the same project will be considered part of the same project for calculating DORA metrics.
@@ -27,6 +27,8 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 2.4 - Start data collection. Choose the desired [mode](#step-2---collect-data-in-a-project) for collecting data.
+### Step 3 - Check the Data in Grafana Dashboards
+To view the collected data, click on the "Dashboards" button located in the top-right corner of Config UI. For detailed instructions, please refer to the [Grafana manuals](Dashboards/GrafanaUserGuide.md).
## Examples
For detailed examples, please refer to the respective documentation files available in this folder, such as [GitHub configuration](GitHub.md), [GitLab configuration](GitLab.md), [Jira configuration](Jira.md) and more. They provide step-by-step instructions and guidance for configuring DevLake with different platforms.
diff --git a/versioned_docs/version-v0.19/Configuration/Tutorial.md b/versioned_docs/version-v0.19/Configuration/Tutorial.md
index b00fb5fa65..c130fb0ebc 100644
--- a/versioned_docs/version-v0.19/Configuration/Tutorial.md
+++ b/versioned_docs/version-v0.19/Configuration/Tutorial.md
@@ -19,7 +19,7 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 1.3 - Add scope config (optional). Define the specific data entities within the data scope for collection or apply transformation rules to the raw API responses.
### Step 2 - Collect Data in a Project
-- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](/docs/GettingStarted/HowToOrganizeDevlakeProjects.md) for more details.
+- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](../GettingStarted/HowToOrganizeDevlakeProjects) for more details.
- Step 2.2 - Associate connection(s) with the project. When associating a connection with a project, you can select specific data scopes. All connections linked to the same project will be considered part of the same project for calculating DORA metrics.
@@ -27,6 +27,8 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 2.4 - Start data collection. Choose the desired [mode](#step-2---collect-data-in-a-project) for collecting data.
+### Step 3 - Check the Data in Grafana Dashboards
+To view the collected data, click on the "Dashboards" button located in the top-right corner of Config UI. For detailed instructions, please refer to the [Grafana manuals](Dashboards/GrafanaUserGuide.md).
## Examples
For detailed examples, please refer to the respective documentation files available in this folder, such as [GitHub configuration](GitHub.md), [GitLab configuration](GitLab.md), [Jira configuration](Jira.md) and more. They provide step-by-step instructions and guidance for configuring DevLake with different platforms.
diff --git a/versioned_docs/version-v0.20/Configuration/Tutorial.md b/versioned_docs/version-v0.20/Configuration/Tutorial.md
index b00fb5fa65..3e48d73878 100644
--- a/versioned_docs/version-v0.20/Configuration/Tutorial.md
+++ b/versioned_docs/version-v0.20/Configuration/Tutorial.md
@@ -19,7 +19,7 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 1.3 - Add scope config (optional). Define the specific data entities within the data scope for collection or apply transformation rules to the raw API responses.
### Step 2 - Collect Data in a Project
-- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](/docs/GettingStarted/HowToOrganizeDevlakeProjects.md) for more details.
+- Step 2.1 - Create a project. DevLake assesses DORA metrics at the project level. For more information on organizing DevLake projects, please refer to [how to organize DevLake projects](../GettingStarted/HowToOrganizeDevlakeProjects) for more details.
- Step 2.2 - Associate connection(s) with the project. When associating a connection with a project, you can select specific data scopes. All connections linked to the same project will be considered part of the same project for calculating DORA metrics.
@@ -27,6 +27,9 @@ To ensure the proper functioning of DevLake, follow these two key steps:
- Step 2.4 - Start data collection. Choose the desired [mode](#step-2---collect-data-in-a-project) for collecting data.
+### Step 3 - Check the Data in Grafana Dashboards
+To view the collected data, click on the "Dashboards" button located in the top-right corner of Config UI. For detailed instructions, please refer to the [Grafana manuals](Dashboards/GrafanaUserGuide.md).
+
## Examples
For detailed examples, please refer to the respective documentation files available in this folder, such as [GitHub configuration](GitHub.md), [GitLab configuration](GitLab.md), [Jira configuration](Jira.md) and more. They provide step-by-step instructions and guidance for configuring DevLake with different platforms.
(incubator-devlake-website) 04/05: docs: add the project organization doc to v0.18
Posted by ly...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 06eb5901a2df333f00ef68998ed3ecfde0f838b4
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Fri Dec 8 20:58:31 2023 +0800
docs: add the project organization doc to v0.18
---
.../create_project_1.png | Bin 0 -> 90993 bytes
.../create_project_2.png | Bin 0 -> 41142 bytes
.../navigate_to_dora_1.png | Bin 0 -> 87703 bytes
.../navigate_to_dora_2.png | Bin 0 -> 206374 bytes
.../observe_metrics_by_project_panel.png | Bin 0 -> 110393 bytes
.../project_pipeline.png | Bin 0 -> 89229 bytes
.../project_use_case_1.png | Bin 0 -> 66828 bytes
.../project_use_case_2.png | Bin 0 -> 380649 bytes
.../GettingStarted/HowToOrganizeDevlakeProjects.md | 225 +++++++++++++++++++++
9 files changed, 225 insertions(+)
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_1.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_1.png
new file mode 100644
index 0000000000..08acd95690
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_1.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_2.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_2.png
new file mode 100644
index 0000000000..f054e5364b
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/create_project_2.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_1.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_1.png
new file mode 100644
index 0000000000..0f89aeb18a
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_1.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_2.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_2.png
new file mode 100644
index 0000000000..4eb27c16f5
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/navigate_to_dora_2.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/observe_metrics_by_project_panel.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/observe_metrics_by_project_panel.png
new file mode 100644
index 0000000000..0b47235994
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/observe_metrics_by_project_panel.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_pipeline.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_pipeline.png
new file mode 100644
index 0000000000..845ef6563d
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_pipeline.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_1.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_1.png
new file mode 100644
index 0000000000..a06e763964
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_1.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_2.png b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_2.png
new file mode 100644
index 0000000000..4cc071558c
Binary files /dev/null and b/versioned_docs/version-v0.18/Configuration/images/HowToOrganizeDevlakeProjects/project_use_case_2.png differ
diff --git a/versioned_docs/version-v0.18/GettingStarted/HowToOrganizeDevlakeProjects.md b/versioned_docs/version-v0.18/GettingStarted/HowToOrganizeDevlakeProjects.md
new file mode 100644
index 0000000000..1b8c1751dd
--- /dev/null
+++ b/versioned_docs/version-v0.18/GettingStarted/HowToOrganizeDevlakeProjects.md
@@ -0,0 +1,225 @@
+---
+title: "How to Organize DevLake Projects"
+sidebar_position: 5
+description: >
+ How to Organize DevLake Projects
+---
+
+This guide provides a step-by-step approach to organizing projects in DevLake, enabling you to measure DORA metrics according to your specific use cases.
+
+## 1. What is a DevLake project?
+On a high level, a DevLake project can be viewed as a real-world project or product line. It represents a specific initiative or endeavor within the software development domain.
+
+On a lower level, a DevLake project is a way of organizing and grouping data from different domains. DevLake uses various [data scopes](/docs/Overview/KeyConcepts.md#data-scope), such as repos, boards, cicd_scopes, and cq_projects as the 'container' to associate different types of data to a specific project. See more on this [doc](/docs/Overview/KeyConcepts.md#project).
+
+## 2. Why is it important to organize projects?
+
+This is crucial due to the fact that DevLake measures DORA metrics at the project level. Each project is associated with specific key entities, such as 'pull requests', 'deployments', and 'incidents', which are used to calculate the corresponding DORA metrics. Therefore, proper project organization ensures accurate and meaningful DORA metric calculations for effective analysis and evaluation.
+
+
+
+> How are four [DORA](../DORA.md) metrics calculated from 'pull requests', 'deployments', and 'incidents'?
+>
+> - [Deployment Frequency](../Metrics/DeploymentFrequency.md): How often does a project `deploys`?
+> - [Lead Time for Changes](../Metrics/LeadTimeForChanges.md): How fast are the `pull requests` delivered?
+> - [Change Failure Rate](../Metrics/CFR.md): How many `deployments` lead to `incidents`?
+> - [Median Time to Restore](../Metrics/MTTR.md): How fast are `incidents` solved?
+
+
+## 3. Challenges in project organization
+There are several challenges associated with organizing projects in DevLake due to different development practices within teams. Some of these challenges include:
+
+- Managing multiple Git repos, issue boards, and CI/CD pipelines within a project.
+- Having a Git repo, issue board, or CI/CD pipeline associated with multiple projects, such as in the case of mono-repos or boards used to track incidents from user feedback.
+- Managing multiple projects within a team and the need to measure DORA metrics at the team level.
+- Projects contributed by multiple teams, with each team requiring the ability to measure their own DORA metrics.
+
+This document serves as a guide to address these challenges and provide assistance in effectively dealing with these diverse development practices.
+
+## 4. General advice
+
+### 4.1. Determining the number of DevLake projects
+
+It is advisable to create DevLake projects that align with the number of real-life projects you have.
+
+For example, if you have a team (Team A) responsible for managing multiple projects, it is recommended to create separate DevLake projects for each individual project instead of creating a single project named 'Team A'. This approach allows for better organization and tracking of metrics specific to each project.
+
+
+### 4.2 Principles of organizing projects
+
+When organizing projects in DevLake, it is important to associate all relevant [data scopes](/docs/Overview/KeyConcepts.md#data-scope), such as repos, issue boards, and CI/CD scopes, with the corresponding DevLake project based on real-life practices.
+
+In situations where a repo or board is shared by multiple projects in real life, it is recommended to include them in all of these projects within DevLake. This is because DevLake cannot differentiate which commits or issues belong to specific projects. Rather than excluding shared resources from DORA measurements, it is advisable to consider them in all relevant projects.
+
+### 4.3 Measuring DORA at the team level
+
+To clarify the concepts, let's define three terms:
+
+- [Project](/docs/Overview/KeyConcepts.md#project): Refers to a real-world project or product line, such as Apache DevLake or Apache Spark. It focuses on the work to be done.
+- Team: Represents a department, such as the 'product team' or 'engineering team'. It focuses on the people and their roles. Note that people within the same team may not always work on the same projects.
+- Project Team: Comprises individuals working on a specific project.
+
+DevLake does support measuring DORA metrics at the project-team level, which is essentially the same as measuring at the project level. However, it is important to note that DevLake does not recommend measuring DORA metrics at the team level. Despite the existence of the 'DORA by team' dashboard contributed by the community. Doing so may introduce inaccuracies and dilute the significance of measuring DORA metrics from the outset.
+
+## 5. Use Cases
+This section demonstrates real-life practices and how they get reflected in DevLake.
+
+Disclaimer: _To keep this guide shorter, some technical details are only mentioned in
+[Use Case 1](HowToOrganizeDevlakeProjects#41-use-case-1-apache-projects),
+so if you read this page for the first time, make sure to go through them in order._
+
+Note: _If you use webhooks, check the [quick note](HowToOrganizeDevlakeProjects#5-about-webhooks) about them below._
+
+### 5.1. Use Case 1: Apache Projects
+Apache Software Foundation (ASF) has and is developing many
+[projects](https://en.wikipedia.org/wiki/List_of_Apache_Software_Foundation_projects).
+
+To take an example we will analyze 2 `projects`: DevLake and [Spark](https://spark.apache.org/).
+Both are independent of each other. Assume that ASF wants to check the health of the development
+and maintenance of these projects with DORA.
+
+DevLake manages 3 `repos`: [incubator-devlake](https://github.com/apache/incubator-devlake),
+[incubator-devlake-website](https://github.com/apache/incubator-devlake-website),
+and [incubator-devlake-helm-chart](https://github.com/apache/incubator-devlake-helm-chart).
+There are many repos related to _Spark_ in one way or another. To keep it simple,
+we will also pick 3 `repos`: [spark](https://github.com/apache/spark),
+[spark-website](https://github.com/apache/spark-website), and [incubator-livy](https://github.com/apache/incubator-livy).
+
+
+
+Both projects use GitHub for storing code (including `pull requests`), `deployments` on GitHub Actions, and `incidents`.
+
+Note: _To avoid confusion between DevLake as a `project` in this use case and DevLake as a platform,
+we will use complete names i.e. `project DevLake` and `platform DevLake` respectively._
+
+#### 5.1.1. Organizing Projects
+First, create two projects on the DevLake platform, one for DevLake and one for Spark.
+These will represent real-world projects.
+
+
+
+
+Once these are created, the connections created in the following steps will be bound to them.
+
+#### 5.1.2. Creating Connections
+
+Since all is on GitHub in this case, we can use just 1 connection with the following properties:
+- it includes all the project's `repos`
+- its scope includes everything we work with (i.e. `pull requests`, `deployments`, and `incidents`)
+
+If you store `incidents` on Jira, for example, you will need to create a separate connection just for them.
+The same applies to `deployments`, a separate connection is needed in case they are stored in Jenkins (or any other host for `deployments`).
+
+#### 5.1.3. Configuring Connections
+This part is described in [GitHub](../Configuration/GitHub.md) connection configuration. Please check the [configuration guide](../Configuration/Tutorial.md) for configuring other data sources.
+
+#### 5.1.4. Using Connections
+
+At this point, we have projects and connections created on the platform DevLake.
+It is time to bind those connections to the projects. To do so, follow the steps described in the [Tutorial](../Configuration/Tutorial.md).
+
+#### 5.1.5. Resulting Metrics
+
+To know if the data of a project is successfully collected to your DORA Dashboard:
+
+
+
+
+If everything goes well, you should see all the 4 charts.
+If something is wrong, and you are puzzled as to why, check out the
+[Debugging Dora Issue Metrics](../Troubleshooting/Dashboard.md#debugging-dora-issue-metrics) page.
+
+#### 5.1.6. How can I observe metrics by project?
+In the same DORA dashboard check out this menu point:
+
+
+The metrics should change when you select or deselect projects, representing the projects you selected.
+
+### 5.2. Use Case 2: Multiple Teams with Distinct Projects
+
+Consider a scenario where a company operates with several teams, each managing one or more projects.
+For illustration, we will explore two such teams: the Payments team and the Internal Tools team.
+Here's a simplified representation of this scenario:
+
+#### Quick Overview:
+- The Payments team works on a single project: “payments”.
+- The Internal Tools team manages two projects: “it-legacy” and “it-new”.
+- Both teams use different sets of tools and boards.
+
+
+
+#### Step-by-Step Simplification:
+1. **Define the Teams and Projects:**
+ - **Payments Team**:
+ - One project: "payments".
+ - **Internal Tools Team**:
+ - Two projects: "it-legacy" and "it-new".
+2. **Understand the Tools**:
+ - Assume both teams utilize GitHub for `repos` and Jenkins for CI/CD.
+ - The _Payments_ team uses Jira boards.
+ - The _Internal Tools_ team uses webhooks for reporting incidents.
+
+#### 5.2.1. Organizing Projects
+
+DORA is effective for observing the impacts of methodology changes within a team.
+From DORA’s standpoint, the concept of distinct `teams` is not recognized; only `projects` exist.
+Adding a `team` concept introduces unnecessary complexity without providing any substantial benefit.
+
+In DevLake, we create three `projects`: _payments_, _it-legacy_, and _it-new_.
+
+It is crucial to maintain **atomic** `projects`, representing the smallest, independent units,
+to prevent complexity and ensure precise data representation. **Atomic** `projects` allow for a more flexible
+and accurate data comparison and combination between `projects`.
+
+#### 5.2.2. Adding Connections
+
+Create just one connection and reuse it across projects by adding data scopes.
+This method optimizes data collection, minimizing redundancy and ensuring more efficient use of resources.
+
+It is NOT recommended to create multiple connections, for instance, GitHub repos, as it
+will increase the time to collect the data due to the storage of multiple copies of shared repos in the database.
+
+The only exception is the webhooks: **we must have 1 connection per project**,
+as this is the only way DevLake can accurately assign `incidents` to the corresponding `project`.
+
+So, in total we will have only these connections:
+- 1 connection for all GitHub `repos` to collect `pull requests`
+- 1 connection to Jenkins to collect all `deployments`
+- 1 connection to Jira to collect `incidents`
+- 2 webhook connections to collect `incidents`: 1 per each `project` that uses webhooks (_it-legacy_ and _it-new_)
+
+The step-by-step [Configuration Guide](../Configuration/Tutorial.md) shows how to both add connections and set scopes as described in the next chapter.
+
+#### 5.2.3. Setting Scopes
+Now, add the connections to our projects and set the scope to them:
+
+For payments `project`:
+- add 1 scope to GitHub connection for _p1...p10_ `repos` to collect their `pull requests`
+- add 1 scope to Jenkins for `deployments` of _p1...p10_ `repos`
+- add 1 scope to Jira to collect `incidents`
+
+For it-legacy `project`:
+- add 1 scope to GitHub for `repos` _it-legacy-1_, _it-legacy-2_, _it-core-1_ and _it-core-2_ to collect their `pull requests`
+- add 1 scope to Jenkins for `deployments` of _it-legacy-1_, _it-legacy-2_, _it-core-1_ and _it-core-2_ `repos`
+- include the _it-legacy_ webhook for collecting `incidents`
+
+For it-new `project`:
+- add 1 scope to GitHub for `repos` _it-new-1_, _it-new-2_, _it-core-1_ and _it-core-2_ to collect their `pull requests`
+- add 1 scope to Jenkins for `deployments` of _it-new-1_, _it-new-2_, _it-core-1_ and _it-core-2_ `repos`
+- include the _it-new_ webhook for collecting `incidents`
+
+#### 5.2.4. Resulting Metrics
+See [5.1.5 Resulting Metrics](HowToOrganizeDevlakeProjects#515-resulting-metrics)
+
+## 6. About Webhooks
+**Assigning a UNIQUE webhook to each project is critical.** This ensures that the DevLake platform
+correctly associates the incoming data with the corresponding project through the webhook.
+
+If you use the same webhook across multiple projects, the data sent by it **will be replicated per each
+project that uses that webhook**. More information available on the [Webhook](/docs/Plugins/webhook.md) page
+
+## 7. Troubleshooting
+
+Please check out the [Debugging DORA Issue Metrics](../Troubleshooting/Dashboard.md#debugging-dora-issue-metrics) to debug DORA dashboard.
+
+If you still run into any problems, please check the [Troubleshooting](/docs/Troubleshooting/Configuration.md) or [create an issue](https://github.com/apache/incubator-devlake/issues)
\ No newline at end of file
(incubator-devlake-website) 01/05: docs: add a quick start for DevLake
Posted by ly...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 83751aa1a0575927d594f7b1a23a9a563ae73efb
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Fri Dec 8 20:54:18 2023 +0800
docs: add a quick start for DevLake
---
docs/GettingStarted/QuickStart.md | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/docs/GettingStarted/QuickStart.md b/docs/GettingStarted/QuickStart.md
new file mode 100644
index 0000000000..686a8ba421
--- /dev/null
+++ b/docs/GettingStarted/QuickStart.md
@@ -0,0 +1,17 @@
+---
+title: "Quick Start"
+description: >
+ The steps to utilize Apache DevLake
+sidebar_position: 1
+---
+
+The key steps to deploy and utilize Apache DevLake.
+
+## Step 1. Install DevLake
+Install DevLake using either <a href="DockerComposeSetup">Docker Compose</a> or <a href="HelmSetup">Helm</a>. If you want to upgrade DevLake to a newer version, please refer to the <a href="Upgrade">upgrade manuals</a>.
+
+## Step 2. Configure DevLake
+Configure DevLake via the Config UI. Follow the <a href="/docs/Configuration/Tutorial">turorial</a> for configuration instructions. If you specifically want to configure DORA metrics, please refer to the <a href="/docs/DORA">DORA manuals</a> for detailed instructions.
+
+## Step 3. View Data in Grafana Dashboards
+After configuring DevLake and collecting data, access the Config UI and click the "Dashboards" button in the top-right corner to view the data in Grafana dashboards. For comprehensive instructions, please refer to the [Grafana manuals](/docs/Configuration/Dashboards/GrafanaUserGuide.md).
(incubator-devlake-website) 02/05: docs: re-organize the index of configuration docs
Posted by ly...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
lynwee pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit e597d264834ab55fd757061e2cfefe6434cb5571
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Fri Dec 8 20:56:59 2023 +0800
docs: re-organize the index of configuration docs
---
docs/Configuration/APIKeys.md | 2 +-
docs/Configuration/AdvancedMode.md | 2 +-
docs/Configuration/BitBucket.md | 2 +-
docs/Configuration/Dashboards/_category_.json | 2 +-
docs/Configuration/GitHub.md | 2 +-
docs/Configuration/GitLab.md | 2 +-
.../HowToOrganizeDevlakeProjects.md | 8 ++++----
docs/Configuration/Jenkins.md | 2 +-
docs/Configuration/Jira.md | 2 +-
docs/Configuration/PagerDuty.md | 2 +-
docs/Configuration/SonarQube.md | 4 ++--
docs/Configuration/Tapd.md | 2 +-
docs/Configuration/TeamConfiguration.md | 2 +-
docs/Configuration/Teambition.md | 4 ++--
docs/Configuration/Zentao.md | 2 +-
docs/Configuration/webhook.md | 4 ++--
docs/GettingStarted/DockerComposeSetup.md | 2 +-
docs/GettingStarted/HelmSetup.md | 2 +-
docs/GettingStarted/Upgrade.md | 2 --
19 files changed, 24 insertions(+), 26 deletions(-)
diff --git a/docs/Configuration/APIKeys.md b/docs/Configuration/APIKeys.md
index b039c67f22..0007722416 100644
--- a/docs/Configuration/APIKeys.md
+++ b/docs/Configuration/APIKeys.md
@@ -1,6 +1,6 @@
---
title: "API Keys"
-sidebar_position: 11
+sidebar_position: 31
description: >
API Keys
---
diff --git a/docs/Configuration/AdvancedMode.md b/docs/Configuration/AdvancedMode.md
index 0d6535c850..3eb936252d 100644
--- a/docs/Configuration/AdvancedMode.md
+++ b/docs/Configuration/AdvancedMode.md
@@ -1,6 +1,6 @@
---
title: "Blueprint Advanced Mode"
-sidebar_position: 9
+sidebar_position: 29
description: >
Using the advanced mode of Config-UI
---
diff --git a/docs/Configuration/BitBucket.md b/docs/Configuration/BitBucket.md
index 9f5e0adea2..cf69391ddb 100644
--- a/docs/Configuration/BitBucket.md
+++ b/docs/Configuration/BitBucket.md
@@ -1,6 +1,6 @@
---
title: "BitBucket Cloud"
-sidebar_position: 2
+sidebar_position: 7
description: Config UI instruction for BitBucket(Cloud)
---
diff --git a/docs/Configuration/Dashboards/_category_.json b/docs/Configuration/Dashboards/_category_.json
index 37da75a8c7..eef7e419cb 100644
--- a/docs/Configuration/Dashboards/_category_.json
+++ b/docs/Configuration/Dashboards/_category_.json
@@ -1,4 +1,4 @@
{
"label": "Dashboard Configuration",
- "position": 10
+ "position": 37
}
diff --git a/docs/Configuration/GitHub.md b/docs/Configuration/GitHub.md
index d38d3454fc..0128e2ea2a 100644
--- a/docs/Configuration/GitHub.md
+++ b/docs/Configuration/GitHub.md
@@ -1,6 +1,6 @@
---
title: "GitHub"
-sidebar_position: 2
+sidebar_position: 9
description: Config UI instruction for GitHub
---
diff --git a/docs/Configuration/GitLab.md b/docs/Configuration/GitLab.md
index 80c465da70..8f5b38decf 100644
--- a/docs/Configuration/GitLab.md
+++ b/docs/Configuration/GitLab.md
@@ -1,6 +1,6 @@
---
title: "GitLab"
-sidebar_position: 3
+sidebar_position: 11
description: Config UI instruction for GitLab
---
diff --git a/docs/GettingStarted/HowToOrganizeDevlakeProjects.md b/docs/Configuration/HowToOrganizeDevlakeProjects.md
similarity index 97%
rename from docs/GettingStarted/HowToOrganizeDevlakeProjects.md
rename to docs/Configuration/HowToOrganizeDevlakeProjects.md
index 23b11aebdf..40fa9b9706 100644
--- a/docs/GettingStarted/HowToOrganizeDevlakeProjects.md
+++ b/docs/Configuration/HowToOrganizeDevlakeProjects.md
@@ -1,6 +1,6 @@
---
title: "How to Organize DevLake Projects"
-sidebar_position: 5
+sidebar_position: 3
description: >
How to Organize DevLake Projects
---
@@ -65,10 +65,10 @@ DevLake does support measuring DORA metrics at the project-team level, which is
This section demonstrates real-life practices and how they get reflected in DevLake.
Disclaimer: _To keep this guide shorter, some technical details are only mentioned in
-[Use Case 1](HowToOrganizeDevlakeProjects.md#41-use-case-1-apache-projects),
+[Use Case 1](HowToOrganizeDevlakeProjects#41-use-case-1-apache-projects),
so if you read this page for the first time, make sure to go through them in order._
-Note: _If you use webhooks, check the [quick note](HowToOrganizeDevlakeProjects.md#5-about-webhooks) about them below._
+Note: _If you use webhooks, check the [quick note](HowToOrganizeDevlakeProjects#5-about-webhooks) about them below._
### 5.1. Use Case 1: Apache Projects
Apache Software Foundation (ASF) has and is developing many
@@ -209,7 +209,7 @@ For it-new `project`:
- include the _it-new_ webhook for collecting `incidents`
#### 5.2.4. Resulting Metrics
-See [5.1.5 Resulting Metrics](HowToOrganizeDevlakeProjects.md#515-resulting-metrics)
+See [5.1.5 Resulting Metrics](HowToOrganizeDevlakeProjects#515-resulting-metrics)
## 6. About Webhooks
**Assigning a UNIQUE webhook to each project is critical.** This ensures that the DevLake platform
diff --git a/docs/Configuration/Jenkins.md b/docs/Configuration/Jenkins.md
index a6476eb9ba..fd41756264 100644
--- a/docs/Configuration/Jenkins.md
+++ b/docs/Configuration/Jenkins.md
@@ -1,6 +1,6 @@
---
title: "Jenkins"
-sidebar_position: 5
+sidebar_position: 13
description: Config UI instruction for Jenkins
---
diff --git a/docs/Configuration/Jira.md b/docs/Configuration/Jira.md
index 6e61c9f3a0..2cd3c0df3f 100644
--- a/docs/Configuration/Jira.md
+++ b/docs/Configuration/Jira.md
@@ -1,6 +1,6 @@
---
title: "Jira"
-sidebar_position: 4
+sidebar_position: 15
description: Config UI instruction for Jira
---
diff --git a/docs/Configuration/PagerDuty.md b/docs/Configuration/PagerDuty.md
index 7882235266..0996240d26 100644
--- a/docs/Configuration/PagerDuty.md
+++ b/docs/Configuration/PagerDuty.md
@@ -1,6 +1,6 @@
---
title: "PagerDuty"
-sidebar_position: 4
+sidebar_position: 17
description: Config UI instruction for PagerDuty
---
diff --git a/docs/Configuration/SonarQube.md b/docs/Configuration/SonarQube.md
index ae2c7335ff..75c435c9f4 100644
--- a/docs/Configuration/SonarQube.md
+++ b/docs/Configuration/SonarQube.md
@@ -1,6 +1,6 @@
---
-title: "SonarQube"
-sidebar_position: 7
+title: "SonarQube Server"
+sidebar_position: 19
description: Config UI instruction for SonarQube
---
diff --git a/docs/Configuration/Tapd.md b/docs/Configuration/Tapd.md
index c518088aac..b575f2f796 100644
--- a/docs/Configuration/Tapd.md
+++ b/docs/Configuration/Tapd.md
@@ -1,6 +1,6 @@
---
title: "TAPD"
-sidebar_position: 6
+sidebar_position: 21
description: Config UI instruction for TAPD
---
diff --git a/docs/Configuration/TeamConfiguration.md b/docs/Configuration/TeamConfiguration.md
index e81392acf0..af8197b846 100644
--- a/docs/Configuration/TeamConfiguration.md
+++ b/docs/Configuration/TeamConfiguration.md
@@ -1,6 +1,6 @@
---
title: "Team Configuration"
-sidebar_position: 10
+sidebar_position: 35
description: >
Team Configuration
---
diff --git a/docs/Configuration/Teambition.md b/docs/Configuration/Teambition.md
index d428f953d6..2623edb153 100644
--- a/docs/Configuration/Teambition.md
+++ b/docs/Configuration/Teambition.md
@@ -1,6 +1,6 @@
---
-title: "Teambition(Beta)"
-sidebar_position: 6
+title: "Teambition(WIP)"
+sidebar_position: 23
description: Config UI instruction for Teambition
---
diff --git a/docs/Configuration/Zentao.md b/docs/Configuration/Zentao.md
index 7497dc9a4c..51a96af3d0 100644
--- a/docs/Configuration/Zentao.md
+++ b/docs/Configuration/Zentao.md
@@ -1,6 +1,6 @@
---
title: "Zentao"
-sidebar_position: 6
+sidebar_position: 27
description: Config UI instruction for Zentao(禅道)
---
diff --git a/docs/Configuration/webhook.md b/docs/Configuration/webhook.md
index 40392e802d..de3fbfdf45 100644
--- a/docs/Configuration/webhook.md
+++ b/docs/Configuration/webhook.md
@@ -1,6 +1,6 @@
---
-title: "Incoming Webhook"
-sidebar_position: 8
+title: "Webhooks"
+sidebar_position: 25
description: Config UI instruction for Webhook
---
diff --git a/docs/GettingStarted/DockerComposeSetup.md b/docs/GettingStarted/DockerComposeSetup.md
index 626ce3cdba..915b016cb5 100644
--- a/docs/GettingStarted/DockerComposeSetup.md
+++ b/docs/GettingStarted/DockerComposeSetup.md
@@ -2,7 +2,7 @@
title: "Install via Docker Compose"
description: >
The steps to install DevLake via Docker Compose
-sidebar_position: 1
+sidebar_position: 2
---
## Prerequisites
diff --git a/docs/GettingStarted/HelmSetup.md b/docs/GettingStarted/HelmSetup.md
index ed36c055ed..054f6b4d71 100644
--- a/docs/GettingStarted/HelmSetup.md
+++ b/docs/GettingStarted/HelmSetup.md
@@ -2,7 +2,7 @@
title: "Install via Helm"
description: >
The steps to install Apache DevLake via Helm for Kubernetes
-sidebar_position: 2
+sidebar_position: 3
---
## Prerequisites
diff --git a/docs/GettingStarted/Upgrade.md b/docs/GettingStarted/Upgrade.md
index 1a170fa394..a55604a48c 100644
--- a/docs/GettingStarted/Upgrade.md
+++ b/docs/GettingStarted/Upgrade.md
@@ -4,8 +4,6 @@ sidebar_position: 3
description: How to upgrade your Apache DevLake to a newer version
---
-## Upgrade Notes
-
1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the inability to decrypt this sensitive information.
2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider important variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.