This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 19cc00bb9a docs: update DORA manuals (#511)
19cc00bb9a is described below
commit 19cc00bb9afc44e5b763cf64bd9395e97e421d02
Author: Louis.z <[email protected]>
AuthorDate: Fri May 5 20:38:25 2023 +0800
docs: update DORA manuals (#511)
* docs: update DORA manuals
* fix: fixed some wording
---------
Co-authored-by: Startrekzky <[email protected]>
Co-authored-by: Yumeng Wang <[email protected]>
---
docs/DORA.md | 75 ++++++++++++---------
static/img/ConfigUI/dora-add-connections.png | Bin 0 -> 56327 bytes
static/img/ConfigUI/dora-add-data-scope.png | Bin 0 -> 49892 bytes
static/img/ConfigUI/dora-add-transformations.png | Bin 0 -> 62743 bytes
static/img/ConfigUI/dora-create-a-blueprint.png | Bin 0 -> 20426 bytes
static/img/ConfigUI/dora-set-sync-policy.png | Bin 0 -> 117628 bytes
.../ConfigUI/dora-set-transformations-github.png | Bin 0 -> 137685 bytes
.../img/ConfigUI/dora-set-transformations-jira.png | Bin 0 -> 90167 bytes
static/img/ConfigUI/project1.png | Bin 28336 -> 32077 bytes
.../img/ConfigUI/webhook-add-data-connections.png | Bin 20756 -> 22397 bytes
static/img/ConfigUI/webhook-add-to-project.png | Bin 0 -> 26985 bytes
static/img/ConfigUI/webhook-connection.png | Bin 78276 -> 90764 bytes
static/img/ConfigUI/webhook-query-deployments.png | Bin 0 -> 404752 bytes
13 files changed, 44 insertions(+), 31 deletions(-)
diff --git a/docs/DORA.md b/docs/DORA.md
index 6e5007db2d..a5d0b11701 100644
--- a/docs/DORA.md
+++ b/docs/DORA.md
@@ -53,56 +53,67 @@ If your CI/CD tools are not listed on the [Supported Data
Sources](./Overview/Su
Let's walk through the DORA implementation process for a team with the
following toolchain
-- Code Hosting: GitHub
+- Source Code Management and Code Review: GitHub
- CI/CD: GitHub Actions + CircleCI
- Issue Tracking: Jira
-Calculating DORA metrics requires three key entities: **changes**,
**deployments**, and **incidents**. Their exact definitions of course depend on
a team's DevOps practice and varies team by team. For the team in this example,
let's assume the following definition:
+Calculating DORA metrics requires three key entities: **Code changes**,
**deployments**, and **incidents**. Their exact definitions of course depend on
a team's DevOps practice and varies team by team. For the team in this example,
let's assume the following definition:
-- Changes: All pull requests in GitHub.
-- Deployments: GitHub action jobs that have "deploy" in their names and
CircleCI's deployment jobs.
-- Incidents: Jira issues whose types are `Crash` or `Incident`
+- Code Changes: All commits and pull requests in GitHub.
+- Deployments: GitHub workflow run whose jobs contain "deploy" in their names
and all CircleCI deployments.
+- Incidents: Jira issues whose type is "DORA Incident"
In the next section, we'll demonstrate how to configure DevLake to implement
DORA metrics for the aforementioned example team.
-### Collect GitHub & Jira data via `blueprint`
+### Collect GitHub & Jira data via `Project`
1. Visit the config-ui at `http://localhost:4000`
-2. Create a project: 'project1'. Go to 'project1' and create a blueprint.
Let's name it "Blueprint for DORA", add a Jira and a GitHub connection. Click
`Next Step`
+2. Create a project: 'project1'. Go to 'project1' and create a blueprint.
+
- 
-3. Select Jira boards and GitHub repos to collect, click `Next Step`
- 
+ 
+
+3. Add a Jira and a GitHub connection. Click `Next Step`
+
+ 
+
+4. Select Jira boards and GitHub repos to collect, click `Next Step`
+
+ 
+
+5. Click the `Associate Transformation` icon to configure the transformation
rules to measure DORA metrics
-4. Click `Add Transformation` to configure for DORA metrics
- 
+ 
-5. To make it simple, fields with a  label
are DORA-related configurations for every data source. Via these fields, you
can define what are "incidents" and "deployments" for each data source. After
all data connections have been configured, click `Next Step`
+ To make it simple, fields with a  label
are DORA-related configurations for every data source. Via these fields, you
can define what "incidents" and "deployments" are for each data source.
- - This team uses Jira issue types `Crash` and `Incident` as "incident", so
choose the two types in field "incident". Jira issues in these two types will
be transformed to "incidents" in DevLake.
- - This team uses the GitHub action jobs named `deploy` and
`build-and-deploy` to deploy, so type in `(?i)deploy` to match these jobs.
These jobs will be transformed to "deployments" in DevLake.
- 
+ - This team uses Jira issue types `DORA Incident` as "incident", so choose
the field `DORA Incident`. Jira issues in this type will be transformed to
"incidents" in DevLake.
+ 
+ - This team uses the GitHub action jobs named `deploy` and
`build-and-push-image` to deploy, so type in `(?i)(deploy|push-image)` to match
these jobs. The workflow runs that these jobs belong to will be transformed to
"deployments" in DevLake.
+ 
- Note: The following example shows where to find GitHub action jobs. It's
easy to mix them up with GitHub workflows.
- 
+ Note: DevLake converts GitHub workflow runs as DevLake deployments in v0.17
and later versions. A workflow run is a DevLake deployment if the name of a
workflow run or one of its jobs that match the regex.
-6. Choose sync frequency, click 'Save and Run Now' to start data collection.
The time to completion varies by data source and depends on the volume of data.
- 
+6. Configure the sync policy and click 'Save and Run Now' to start data
collection. The time to completion varies by the API rate limits of different
data sources and the volume of data.
-For more details, please refer to our [blueprint
manuals](./Configuration/Tutorial).
+ 
+
+For more details, please refer to our [blueprint
manuals](Configuration/Tutorial.md).
### Collect CircleCI data via `webhook`
Using CircleCI as an example, we demonstrate how to actively push data to
DevLake using the Webhook approach, in cases where DevLake doesn't have a
plugin specific to that tool to pull data from your data source.
-7. Go to the 'Data Connections' page. Create a webhook.
-
+7. In Project1's detailed page, switch to tab 'Incoming Webhooks'. Add a
webhook called 'CircleCI'
+
+ 
+
+ 
-We recommend that you give your webhook connection a unique name so that you
can identify and manage where you have used it later.
-8. Create a Project first, choose Incoming Webhooks, then you can `Add a
Webhook` or `Select Existing Webhooks`. And click "Generate POST URL". DevLake
will generate URLs that you can send JSON payloads to push `deployments` and
`incidents` to Devlake. Copy the `Deployment` curl command.
- 
+8. Click "Generate POST URL". DevLake will generate URLs that you can send
JSON payloads to push `deployments` and `incidents` to Devlake. Copy the
`Deployment` curl command.
+
9. Now head to your CircleCI's pipelines page in a new tab. Find your
deployment pipeline and click `Configuration File`
@@ -140,7 +151,7 @@ jobs:
# Send the request to DevLake after deploy
# The values start with a '$CIRCLE_' are CircleCI's built-in
variables
- curl http://127.0.0.1:4000/api/plugins/webhook/1/deployments -X
'POST' -d "{
+ curl http://127.0.0.1:4000/api/plugins/webhook/2/deployments -X
'POST' -d "{
\"commit_sha\":\"$CIRCLE_SHA1\",
\"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
\"start_time\":\"$start_time\"
@@ -156,18 +167,20 @@ workflows:
If you have set a [username/password](GettingStarted/Authentication.md) for
Config UI, you need to add them to the curl to register a deployment:
```
-curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u
'username:password' -d '{
+curl https://sample-url.com/api/plugins/webhook/2/deployments -X 'POST' -u
'username:password' -d '{
\"commit_sha\":\"$CIRCLE_SHA1\",
\"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
\"start_time\":\"$start_time\"
}'
```
-11. Run the modified CircleCI pipeline. Check to verify that the request has
been successfully sent.
+11. Run the modified CircleCI pipeline. Check that the request has been
successfully sent.
+
-12. You will find the corresponding `deployments` in table.cicd_tasks in
DevLake's database.
- 
+12. You will find the `deployments` pushed from CircleCI in table
[cicd_deployment_commits](DataModels/DevLakeDomainLayerSchema.md#domain-4---cicd)
in DevLake's database.
+
+ 
### View and customize DevLake's DORA dashboard
diff --git a/static/img/ConfigUI/dora-add-connections.png
b/static/img/ConfigUI/dora-add-connections.png
new file mode 100644
index 0000000000..8e47b96ac7
Binary files /dev/null and b/static/img/ConfigUI/dora-add-connections.png differ
diff --git a/static/img/ConfigUI/dora-add-data-scope.png
b/static/img/ConfigUI/dora-add-data-scope.png
new file mode 100644
index 0000000000..9743c0b550
Binary files /dev/null and b/static/img/ConfigUI/dora-add-data-scope.png differ
diff --git a/static/img/ConfigUI/dora-add-transformations.png
b/static/img/ConfigUI/dora-add-transformations.png
new file mode 100644
index 0000000000..230301fc0c
Binary files /dev/null and b/static/img/ConfigUI/dora-add-transformations.png
differ
diff --git a/static/img/ConfigUI/dora-create-a-blueprint.png
b/static/img/ConfigUI/dora-create-a-blueprint.png
new file mode 100644
index 0000000000..3c8f9b3041
Binary files /dev/null and b/static/img/ConfigUI/dora-create-a-blueprint.png
differ
diff --git a/static/img/ConfigUI/dora-set-sync-policy.png
b/static/img/ConfigUI/dora-set-sync-policy.png
new file mode 100644
index 0000000000..aa21c32a27
Binary files /dev/null and b/static/img/ConfigUI/dora-set-sync-policy.png differ
diff --git a/static/img/ConfigUI/dora-set-transformations-github.png
b/static/img/ConfigUI/dora-set-transformations-github.png
new file mode 100644
index 0000000000..f0a49356db
Binary files /dev/null and
b/static/img/ConfigUI/dora-set-transformations-github.png differ
diff --git a/static/img/ConfigUI/dora-set-transformations-jira.png
b/static/img/ConfigUI/dora-set-transformations-jira.png
new file mode 100644
index 0000000000..ce86e5a6f5
Binary files /dev/null and
b/static/img/ConfigUI/dora-set-transformations-jira.png differ
diff --git a/static/img/ConfigUI/project1.png b/static/img/ConfigUI/project1.png
index 6b1a6dfee3..f2de5093e7 100644
Binary files a/static/img/ConfigUI/project1.png and
b/static/img/ConfigUI/project1.png differ
diff --git a/static/img/ConfigUI/webhook-add-data-connections.png
b/static/img/ConfigUI/webhook-add-data-connections.png
index 895a23d511..4b1b050893 100644
Binary files a/static/img/ConfigUI/webhook-add-data-connections.png and
b/static/img/ConfigUI/webhook-add-data-connections.png differ
diff --git a/static/img/ConfigUI/webhook-add-to-project.png
b/static/img/ConfigUI/webhook-add-to-project.png
new file mode 100644
index 0000000000..2eebdee02b
Binary files /dev/null and b/static/img/ConfigUI/webhook-add-to-project.png
differ
diff --git a/static/img/ConfigUI/webhook-connection.png
b/static/img/ConfigUI/webhook-connection.png
index c7abe29e17..231830b155 100644
Binary files a/static/img/ConfigUI/webhook-connection.png and
b/static/img/ConfigUI/webhook-connection.png differ
diff --git a/static/img/ConfigUI/webhook-query-deployments.png
b/static/img/ConfigUI/webhook-query-deployments.png
new file mode 100644
index 0000000000..44ade1993f
Binary files /dev/null and b/static/img/ConfigUI/webhook-query-deployments.png
differ
