KucherenkoSerhiy commented on code in PR #637: URL: https://github.com/apache/incubator-devlake-website/pull/637#discussion_r1329363602
########## docs/_temp/HowToOrganizeDevlakeProjects.md: ########## @@ -0,0 +1,189 @@ +--- +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 `incidents` inside boards. + +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 `incidents` per `deploys` does the team have? (a.k.a. [Change Failure Rate](docs/Metrics/CFR.md)) + - How fast are these `incidents` solved? (a.k.a. [Median Time to Restore](docs/Metrics/MTTR.md)) + +All these questions/metrics are based on either `pull requests`, `deployments`, or `incidents`. +Note: all three are completely separate entities and associated only to their project. + +#### General advice + +There are 3 red lines when it comes to structuring your DevLake `projects`: + +But when we scale this up, a 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 +- A `board` contains incidents of multiple teams or projects +- A `repository` is managed by multiple teams or projects, e.g. a monorepo +- A `pipeline` can trigger deployments in multiple repositories +- Some organizations want to measure DORA based on projects, and some want to measure it by 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. +A DevLake project is a grouping of `pull requests`, `deployments`, or `incidents`. It can be seen as a real-world project or product line. DevLake measures DORA metrics for each project. + + + +_Note: It does not matter if a team works on a particular repository more than another. +The metrics are calculated over the entire set of repos, and the values are accumulated. +More on that: [Debugging DORA Issue Metrics](docs/Troubleshooting/Dashboard.md#debugging-dora-issue-metrics)_ + +## 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 `incidents` +either by your specific projects, by teams, technology, or any other way. + +The examples below show the patterns of how to organize your projects. +To keep things simple we assume that we work with **GitHub** repos, **Jira** boards, +and **Jenkins CI/CD** deploys in each GitHub repo. + +The same would apply to other repos (e.g. GitLab or BitBucket), boards (e.g. TAPD), +or CI/CD (e.g. GitLab CI, Azure DevOps). + +## 4. Use Cases +This section demonstrates real-life situations and how they get reflected in DevLake. + +Quick note: to keep this guide shorter and more concise, some technical details are only mentioned in the use case 1, +so if you read this page for the first time, make sure to go through them in order. + +Quick note 2: if you use webhooks, check the [quick note](HowToOrganizeDevlakeProjects.md#5-note-about-webhooks) about them below. + +### 4.1. Use Case 1: Projects DevLake and DevStream +DevLake and [DevStream](https://github.com/devstream-io/devstream) are both Apache `projects`. Review Comment: Haha, thanks for pointing out the funny mistake and guidance! Regarding the comparing projects, I'd instead check the health of the development and maintenance with DORA of separate projects rather than compare themselves. There may be many differences between assignments (size of the team/community, problem the project solves, project's age, etc.). Comparing the projects between themselves might mislead to why use DORA in the first place. Many companies end up having projects organized by teams, so this leads to comparing those teams. That might lead to higher competitiveness and toxicity and create more problems instead of solving them. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
