You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by zk...@apache.org on 2022/07/26 11:39:32 UTC
[incubator-devlake-website] branch main updated: fix: update the team configuration
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 36a772e2 fix: update the team configuration
36a772e2 is described below
commit 36a772e270a53c014d5f91eeb6d69459508c5150
Author: Startrekzky <ka...@merico.dev>
AuthorDate: Tue Jul 26 19:24:23 2022 +0800
fix: update the team configuration
---
docs/UserManuals/TeamConfiguration.md | 53 ++++++++++++++++++-----------------
1 file changed, 27 insertions(+), 26 deletions(-)
diff --git a/docs/UserManuals/TeamConfiguration.md b/docs/UserManuals/TeamConfiguration.md
index d85f96bd..b81df200 100644
--- a/docs/UserManuals/TeamConfiguration.md
+++ b/docs/UserManuals/TeamConfiguration.md
@@ -6,12 +6,12 @@ description: >
---
## What is 'Team Configuration' and how it works?
-To render and organize metrics by team, DevLake needs to know about the team configuration in an organization, specifically:
+To organize and display metrics by `team`, Apache DevLake needs to know about the team configuration in an organization, specifically:
-1. What're the teams?
-2. Who're the users?
+1. What are the teams?
+2. Who are the users(unified identities)?
3. Which users belong to a team?
-4. Which accounts belong to a user?
+4. Which accounts(identities in specific tools) belong to the same user?
Each of the questions above corresponds to a table in DevLake's schema, illustrated below:
@@ -22,8 +22,8 @@ Each of the questions above corresponds to a table in DevLake's schema, illustra
3. `team_users` table stores which users belong to a team.
4. `user_accounts` table stores which accounts belong to a user. An `account` refers to an identiy in a DevOps tool and is automatically created when importing data from that tool. For example, a `user` may have a GitHub `account` as well as a Jira `account`.
-DevLake uses a simple heuristic algorithm based on names and emails to automatically map accounts to users and populate the `user_accounts` table.
-When DevLake cannot confidently map an `account` to a `user` due to insufficient information, it allows DevLake users to manually configure the mapping to ensure accuracy and completeness.
+Apache DevLake uses a simple heuristic algorithm based on emails and names to automatically map accounts to users and populate the `user_accounts` table.
+When Apache DevLake cannot confidently map an `account` to a `user` due to insufficient information, it allows DevLake users to manually configure the mapping to ensure accuracy and integrity.
## A step-by-step guide
@@ -33,19 +33,19 @@ The overall workflow is:
1. Create the `teams` table
2. Create the `users` and `team_users` table
3. Populate the `accounts` table via data collection
-4. Run a heursitic algorithm to populate `user_accounts` table
+4. Run a heuristic algorithm to populate `user_accounts` table
5. Manually update `user_accounts` when the algorithm can't catch everything
Note:
-1. Please replace `/path/to/*.csv` with the absolute path of the csv file you'd like to upload.
-2. Please replace `127.0.0.1:8080` with your actual DevLake service IP and port number.
+1. Please replace `/path/to/*.csv` with the absolute path of the CSV file you'd like to upload.
+2. Please replace `127.0.0.1:8080` with your actual Apache DevLake service IP and port number.
## Step 1 - Create the `teams` table
You can create the `teams` table by sending a PUT request to `/plugins/org/teams.csv` with a `teams.csv` file. To jumpstart the process, you can download a template `teams.csv` from `/plugins/org/teams.csv?fake_data=true`. Below are the detailed instructions:
-a. Dowload the template `teams.csv` file
+a. Download the template `teams.csv` file
i. GET http://127.0.0.1:8080/plugins/org/teams.csv?fake_data=true (pasting the URL into your browser will download the template)
@@ -53,15 +53,15 @@ a. Dowload the template `teams.csv` file
curl --location --request GET 'http://127.0.0.1:8080/plugins/org/teams.csv?fake_data=true'
-b. Fill out `teams.csv` file and upload to DevLake
+b. Fill out `teams.csv` file and upload it to DevLake
- i. Fill out `teams.csv` with your org data. Please don't modify the colume headers or the file suffix.
+ i. Fill out `teams.csv` with your org data. Please don't modify the column headers or the file suffix.
ii. Upload `teams.csv` to DevLake with the following curl command:
curl --location --request PUT 'http://127.0.0.1:8080/plugins/org/teams.csv' --form 'file=@"/path/to/teams.csv"'
iii. The PUT request would populate the `teams` table with data from `teams.csv` file.
- You can connect to the database and verify the data in `teams` table.
+ You can connect to the database and verify the data in the `teams` table.
See Appendix for how to connect to the database.
@@ -71,7 +71,7 @@ b. Fill out `teams.csv` file and upload to DevLake
You can create the `users` and `team_users` table by sending a single PUT request to `/plugins/org/users.csv` with a `users.csv` file. To jumpstart the process, you can download a template `users.csv` from `/plugins/org/users.csv?fake_data=true`. Below are the detailed instructions:
-a. Dowload the template `users.csv` file
+a. Download the template `users.csv` file
i. GET http://127.0.0.1:8080/plugins/org/users.csv?fake_data=true (pasting the URL into your browser will download the template)
@@ -81,7 +81,7 @@ a. Dowload the template `users.csv` file
b. Fill out `users.csv` and upload to DevLake
- i. Fill out `users.csv` with your org data. Please don't modify the colume headers or the file suffix
+ i. Fill out `users.csv` with your org data. Please don't modify the column headers or the file suffix
ii. Upload `users.csv` to DevLake with the following curl command:
curl --location --request PUT 'http://127.0.0.1:8080/plugins/org/users.csv' --form 'file=@"/path/to/users.csv"'
@@ -98,8 +98,9 @@ c. If you ever want to update `team_users` or `users` table, simply upload the u
## Step 3 - Populate the `accounts` table via data collection
The `accounts` table is automatically populated when you collect data from data sources like GitHub and Jira through DevLake.
-For example, the GitHub plugin would create one entry in `accounts` table for each GitHub user involved in your repository.
-For demo purpose, we'll insert some mock data into the `accounts` table using SQL:
+
+For example, the GitHub plugin would create one entry in the `accounts` table for each GitHub user involved in your repository.
+For demo purposes, we'll insert some mock data into the `accounts` table using SQL:
```
INSERT INTO `accounts` (`id`, `created_at`, `updated_at`, `_raw_data_params`, `_raw_data_table`, `_raw_data_id`, `_raw_data_remark`, `email`, `full_name`, `user_name`, `avatar_url`, `organization`, `created_date`, `status`)
@@ -111,7 +112,7 @@ VALUES
-## Step 4 - Run a heursitic algorithm to populate `user_accounts` table
+## Step 4 - Run a heuristic algorithm to populate `user_accounts` table
Now that we have data in both the `users` and `accounts` table, we can tell DevLake to infer the mappings between `users` and `accounts` with a simple heuristic algorithm based on names and emails.
@@ -143,8 +144,8 @@ b. After successful execution, you can verify the data in `user_accounts` in the
## Step 5 - Manually update `user_accounts` when the algorithm can't catch everything
It is recommended to examine the generated `user_accounts` table after running the algorithm.
-We'll domonstrate how to manually update `user_accounts` when the mapping is inaccurate/incomplete in this section.
-To make manual verification easier, DevLake provides an API for users to download `user_accounts` as a csv file.
+We'll demonstrate how to manually update `user_accounts` when the mapping is inaccurate/incomplete in this section.
+To make manual verification easier, DevLake provides an API for users to download `user_accounts` as a CSV file.
Alternatively, you can verify and modify `user_accounts` all by SQL, see Appendix for more info.
a. GET http://127.0.0.1:8080/plugins/org/user_account_mapping.csv(pasting the URL into your browser will download the file). If you prefer using curl:
@@ -154,8 +155,8 @@ curl --location --request GET 'http://127.0.0.1:8080/plugins/org/user_account_ma
-b. If you find the mapping inaccurate or incomplete, you can modify the `user_account_mapping.csv` file and then upload to DevLake.
-For example, here we change the `UserId` of row Id=github:GithubAccount:1:1234 in the `user_account_mapping.csv` file to 2.
+b. If you find the mapping inaccurate or incomplete, you can modify the `user_account_mapping.csv` file and then upload it to DevLake.
+For example, here we change the `UserId` of row 'Id=github:GithubAccount:1:1234' in the `user_account_mapping.csv` file to 2.
Then we upload the updated `user_account_mapping.csv` file with the following curl command:
```
@@ -166,18 +167,18 @@ c. You can verify the data in the `user_accounts` table has been updated.
-## Appendix: how to connect to the database
+## Appendix A: how to connect to the database
-Here we use MySQL as an example. You can install database management tools like Sequel Ace, DataGrip, MySQLWorkbench, and etc.
+Here we use MySQL as an example. You can install database management tools like Sequel Ace, DataGrip, MySQLWorkbench, etc.
-Or through command line:
+Or through the command line:
```
mysql -h <ip> -u <username> -p -P <port>
```
-## Appendix: how to examine `user_accounts` via SQL
+## Appendix B: how to examine `user_accounts` via SQL
```
SELECT a.id as account_id, a.email, a.user_name as account_user_name, u.id as user_id, u.name as real_name