Update Azure DevOps manuals in v0.18 (#607)

* fix: typos and deployment config for GitLab * fix: typos for GitLab and Jira manuals * docs: update Azure manuals * fix: adjust additional settings in Azure's manual --------- Co-authored-by: Startrekzky <[email protected]>
apache · Jul 28, 2023 · c799b41 · c799b41
1 parent 5d6439d
commit c799b41
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 30 deletions.
diff --git a/docs/Configuration/AzureDevOps.md b/docs/Configuration/AzureDevOps.md
@@ -8,30 +8,34 @@ Visit Config UI at: `http://localhost:4000`.
 
 ## Step 1 - Add Data Connections
 
+On the Connections page, you can select GitHub and create a new connection or it.
+
+### Step 1.1 - Authentication
+
 ![azuredevops-create-a-connection](images/azuredevops-create-a-connection.png)
 
-### Connection Name
+#### Connection Name
 
 Give your connection a unique name to help you identify it in the future.
 
-### Token
+#### Token
 
 Paste your Azure DevOps personal access token (PAT) here. You can click on "Learn about how to create a PAT" to get instructions on how to create a PAT.
 Make sure that the Organization field is set to "All accessible organizations" when creating the PAT.
 
-### Test and Save Connection
+#### Test and Save Connection
 
 Click `Test Connection`, if the connection is successful, click `Save Connection` to add the connection.
 
-## Step 2 - Setting Data Scope
+### Step 1.2 - Add Data Scopes
 
 ![azuredevops-set-data-scope](images/azuredevops-set-data-scope.png)
 
-### Select repositories
+#### Select repositories
 
 Select the repositories you want to collect data from.
 
-### Data Entities
+#### Data Entities
 
 Azure DevOps supports the following data entities.
 
@@ -40,22 +44,52 @@ Azure DevOps supports the following data entities.
 - Code Review: pull requests and their commits.
 
 
-## Step 3 - Adding Transformation Rules (Optional)
+### Step 1.3 - Add Scope Config (Optional)
 
-![azuredevops-set-transformation](images/azuredevops-set-transformation.png)
+Scope config contains two parts: 
+- The entities of which domain you wish to collect: Usually, you don't have to modify this part. However, if you don't want to collect certain Azure DevOps entities, you can unselect some entities to accelerate the collection speed.
+  - Source Code Management: Azure repos, refs, commits, etc.
+  - Code Review: Azure PRs, PR comments and reviews, etc.
+  - CI/CD: Azure pipelines, jobs, etc.
+  - Cross Domain: Azure accounts, etc.
+- The transformations on the Azure DevOps data you are going to collect. 
 
-This set of configurations is used for calculating [DORA metrics](../DORA.md).
 
-If you'd like to define `deployments` with Azure DevOps, you can set the following options:
-- Deployment regex: Azure DevOps builds or jobs whose names match this regex will be registered as deployments
-- Production: Azure DevOps builds or jobs whose names match this regex will be assigned environment 'PRODUCTION'
+The transformations are mainly used for calculating [DORA metrics](../DORA.md), so DevLake needs to know what are `deployments` in your Azure Pipelines. You can configure:
+    - Regex for `Deployments`: Azure DevOps pipeline or one of its jobs whose names match this regex will be registered as deployments in DevLake
+    - Regex for `Production` environment: Azure DevOps pipeline or one of its jobs whose names match this regex will be considered as a PRODUCTION deployment.
 
-### Additional Settings (Optional)
+![azuredevops-set-transformation](images/azuredevops-set-transformation.png)
 
-The additional settings are RefDiff options:
+The additional settings for transformations are RefDiff options:
 - Tags Limit: the number of tags to compare.
 - Tags Pattern: Only tags that match the given regex are taken into account.
 
+## Step 2 - Collect Data in a Project
+### Step 2.1 - Create a Project
+Collecting Azure DevOps data requires creating a project first. You can visit the Project page from the side menu and create a new project by following the instructions on the user interface.
+
+![create-a-project](images/create-a-project.png)
+
+### Step 2.2 - Add a Azure DevOps Connection
+You can add a previously configured GitLab connection to the project and select the boards for which you wish to collect the data for. 
+Please note: if you don't see the repositories you are looking for, please check if you have added them to the connection first.
+
+![add-a-connection](images/add-a-connection-project.png)
+
+### Step 2.3 - Set the Sync Policy
+There are three settings for Sync Policy:
+- Data Time Range: You can select the time range of the data you wish to collect. The default is set to the past six months.
+- Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or entering a cron code to specify your prefered schedule.
+- Skip Failed Tasks: sometime a few tasks may fail in a long pipeline; you can choose to skip them to avoid spending more time in running the pipeline all over again.
+
+![sync-policy](images/sync-policy.png)
+
+### Step 2.4 - Start Data Collection
+Click on "Collect Data" to start collecting data for the whole project. You can check the status in the Status tab on the same page.
+![collect-data](images/collect-data.png)
+
+
 ## Troubleshooting
 
 If you run into any problem, please check the [Troubleshooting](/Troubleshooting/Configuration.md) or [create an issue](https://github.com/apache/incubator-devlake/issues)
diff --git a/docs/Configuration/GitHub.md b/docs/Configuration/GitHub.md
@@ -10,7 +10,7 @@ Visit Config UI at: `http://localhost:4000`.
 
 On the Connections page, you can select GitHub and create a new connection or it.
 
-### Stept 1.1 - Authentication
+### Step 1.1 - Authentication
 ![github-add-data-connections](images/github-create-a-connection.png)
 
 #### Connection Name

diff --git a/docs/Configuration/GitLab.md b/docs/Configuration/GitLab.md
@@ -10,7 +10,7 @@ Visit Config UI: `http://localhost:4000`.
 
 On the Connections page, you can select GitHub and create a new connection or it.
 
-### Stept 1.1 - Authentication
+### Step 1.1 - Authentication
 
 ![gitlab-add-data-connections](images/gitlab-create-a-connection.png)
 
@@ -74,14 +74,14 @@ Choose the GitLab repositories you wish to collect either by finding them in the
 
 ### Step 1.3 - Add Scope Config (Optional)
 Scope config contains two parts: 
-- The entities of which domain you wish to collect: 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.
+- The entities of which domain you wish to collect: Usually, you don't have to modify this part. However, if you don't want to collect certain GitLab entities, you can unselect some entities to accelerate the collection speed.
   - Issue Tracking: GitLab issues, issue comments, issue labels, etc.
   - Source Code Management: GitLab repos, refs, commits, etc.
   - Code Review: GitLab MRs, MR comments and reviews, etc.
   - CI/CD: GitLab pipelines, jobs, etc.
   - Cross Domain: GitLab accounts, etc.
 - The transformations on the GitLab data you are going to collect.
-  - The details of the transformations will be exlained below.
+  - The details of the transformations will be explained below.
   - Without adding transformation rules, you can still view some of the dashboards.
   - Each GitLab repo has at most ONE set of transformations.
 
@@ -94,16 +94,15 @@ This set of configurations is used for calculating [DORA metrics](../DORA.md).
 
 If you're using GitLab CI to conduct `deployments`, please select "Detect Deployment from Jobs in GitLab CI", and input the RegEx in the following fields:
 
-- Deployment: A GitLab CI job with a name that matches the given regEx will be considered as a deployment.
-- Production: A GitLab CI job with a name that matches the given regEx will be considered a job in the production environment.
+- Deployment: The name of the GitLab pipeline or one of its jobs matches the given regEx will be considered as a deployment.
+- Production: If the name also matches the PRODUCTION regEx, the deployment will be considered a PRODUCTION deployment.
 
-By the above two fields, DevLake can identify a production deployment among massive CI jobs.
+By the above two fields, DevLake can identify a production deployment among massive GitLab CI pipelines.
 
-You can also select "Not using Jobs in GitLab CI as Deployments" if you're not using GitLab CI to conduct deployments.
 
 ## Step 2 - Collect Data in a Project
 ### Step 2.1 - Create a Project
-Collecing GitLab data reuiqres creating a project first. You can visit the Project page from the side menu and create a new project by following the instructions on the user interface.
+Collecting GitLab data requires creating a project first. You can visit the Project page from the side menu and create a new project by following the instructions on the user interface.
 
 ![create-a-project](images/create-a-project.png)
 
@@ -116,7 +115,7 @@ Please note: if you don't see the repositories you are looking for, please check
 ### Step 2.3 - Set the Sync Policy
 There are three settings for Sync Policy:
 - Data Time Range: You can select the time range of the data you wish to collect. The default is set to the past six months.
-- 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.
+- Sync Frequency: You can choose how often you would like to sync your data in this step by selecting a sync frequency option or entering a cron code to specify your prefered schedule.
 - Skip Failed Tasks: sometime a few tasks may fail in a long pipeline; you can choose to skip them to avoid spending more time in running the pipeline all over again.
 
 ![sync-policy](images/sync-policy.png)

diff --git a/docs/Configuration/Jira.md b/docs/Configuration/Jira.md
@@ -94,7 +94,7 @@ Choose the Jira boards to collect.
 
 ### Step 1.3 - Add Scope Config (Optional)
 Scope config contains two parts: 
-- The entities of which domain you wish to collect: Usually, you don't have to modify this part. However, if you don't want to collect certain Jira entities, you can unselect some entities to accerlerate the collection speed.
+- The entities of which domain you wish to collect: Usually, you don't have to modify this part. However, if you don't want to collect certain Jira entities, you can unselect some entities to accelerate the collection speed.
    - Issue Tracking: Jira issues, issue comments, issue labels, etc.
    - Cross Domain: Jira accounts, etc.
 - The transformations on the Jira data you are going to collect

diff --git a/docs/Configuration/images/azuredevops-set-transformation.png b/docs/Configuration/images/azuredevops-set-transformation.png
diff --git a/versioned_docs/version-v0.17/Configuration/GitLab.md b/versioned_docs/version-v0.17/Configuration/GitLab.md
@@ -89,12 +89,10 @@ This set of configurations is used for calculating [DORA metrics](../DORA.md).
 
 If you're using GitLab CI to conduct `deployments`, please select "Detect Deployment from Jobs in GitLab CI", and input the RegEx in the following fields:
 
-- Deployment: A GitLab CI job with a name that matches the given regEx will be considered as a deployment.
-- Production: A GitLab CI job with a name that matches the given regEx will be considered a job in the production environment.
+- Deployment: The name of the GitLab pipeline or one of its jobs matches the given regEx will be considered as a deployment.
+- Production: If the name also matches the PRODUCTION regEx, the deployment will be considered a PRODUCTION deployment.
 
-By the above two fields, DevLake can identify a production deployment among massive CI jobs.
-
-You can also select "Not using Jobs in GitLab CI as Deployments" if you're not using GitLab CI to conduct deployments.
+By the above two fields, DevLake can identify a production deployment among massive GitLab CI pipelines.
 
 ## Step 4 - Setting Sync Policy