From 97c66623958bcc728241099fe5b4e2e1ce495055 Mon Sep 17 00:00:00 2001 From: Serhiy Kucherenko Date: Thu, 31 Aug 2023 14:41:30 +0200 Subject: [PATCH 01/24] docs: WIP how to organize devlake projects --- docs/_temp/Installation.md | 64 +++++++++++++++++++++++++++++++++ docs/_temp/project_simple.png | Bin 0 -> 26455 bytes docs/_temp/projects_scaled.png | Bin 0 -> 91508 bytes 3 files changed, 64 insertions(+) create mode 100644 docs/_temp/Installation.md create mode 100644 docs/_temp/project_simple.png create mode 100644 docs/_temp/projects_scaled.png diff --git a/docs/_temp/Installation.md b/docs/_temp/Installation.md new file mode 100644 index 00000000000..e77a37b934d --- /dev/null +++ b/docs/_temp/Installation.md @@ -0,0 +1,64 @@ +--- +title: "How to Organize Devlake Projects" +sidebar_position: 1 +description: > + How to Organize Devlake Projects +--- + +## 1. Introduction +A typical team of developers works with `pull requests`, `deployments`, and `issues` (a.k.a. Bugs for deployment). + +Based on such, we want to measure their productivity and stability. This is how [DORA](docs/DORA.md) does that: +- Productivity: + - How many times does the team `deploy`? (a.k.a. [Deployment Frequency](docs/Metrics/DeploymentFrequency.md)) + - How fast are the `pull requests` resolved? (a.k.a. [Lead Time](docs/Metrics/LeadTimeForChanges.md)) +- Stability: + - How many `issues` per `deploys` does the team have? (a.k.a. [Change Failure Rate](docs/Metrics/CFR.md)) + - How fast are these `issues` solved? (a.k.a. [Median Time to Restore](docs/Metrics/MTTR.md)) + +All these questions/metrics are based on either `pull requests`, `deployments`, or `issues`. + +But when we scale this up, few problems arise: +- A team usually works with multiple repositories +- A team also might work on different projects, and we want to measure these projects separately (e.g. it is not the same to work on a big old legacy than on a greenfield) +- There may be multiple teams + +This is where the `project` concept comes to play. + +## 2. What is a DevLake project? +In the real world, a project is something being built and/or researched to solve some problem or to open new grounds. +In software development, a project is just a grouping of something. In DevLake, a `project` is a grouping of `pull requests`, `deployments`, or `issues`. + +![](project_simple.png) + +## 3. As a team lead, how many DevLake projects do I need? + +Because of its simplicity, the concept is flexible: you decide how to arrange `pull requests`, `deployments`, and `issues` +either by your specific projects, by teams, technology, or any other way. + +Let's consider an example: +- There is 1 team working on 2 projects +- The first project consists of 3 repositories with one of them worked most of the time +- The second project only has 2 repos worked equal time among them + +![](projects_scaled.png) + +Note that: +- If instead there were 2 separate teams, the structure would remain the same. The only thing to consider changing is the name of the project +- The same applies to any other way of arranging the projects +- It does not matter if a particular repository it touched more than the others. Why? The answer is in the section below + +### 3.1. What am I looking for with DORA? +TODO: explain right and wrong ways to use DORA + +## 4. How do we organize projects when there is data from multiple connection(s)? +TODO + +### 4.1. Webhooks +TODO + +## 5. How do I know if the data of a project is successfully collected? +TODO + +## 6. How can I observe metrics by project? +TODO diff --git a/docs/_temp/project_simple.png b/docs/_temp/project_simple.png new file mode 100644 index 0000000000000000000000000000000000000000..bdfc0e95e29daf0732b1a0362572510fe2472e32 GIT binary patch literal 26455 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